doc-detective-common 4.21.0 → 4.23.0

package/dist/index.cjs

@@ -2548,7 +2548,7 @@ var schemas_default = {
                   ]
                 },
                 browsers: {
-                  description: "Browsers to run tests on.",
+                  description: "Browsers to run tests on. On a mobile (`android`/`ios`) platform entry, the browser runs on the managed device: `chrome` on Android, `safari` on iOS (other combinations skip the context), and it fills in automatically when omitted. Device browsers don't take desktop display config: authored `window`/`viewport` dimensions and `headless: false` are rejected on mobile entries (the device owns its display \u2014 control it via the device descriptor's `headless`/`deviceType`); `headless: true` matches this schema's default and is ignored.",
                   anyOf: [
                     {
                       type: "string",
@@ -2559,7 +2559,7 @@ var schemas_default = {
                         "safari",
                         "webkit"
                       ],
-                      $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                      $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                     },
                     {
                       type: "object",
@@ -2578,7 +2578,7 @@ var schemas_default = {
                             "safari",
                             "webkit"
                           ],
-                          $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                          $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                         },
                         explicit: {
                           type: "boolean",
@@ -2638,7 +2638,7 @@ var schemas_default = {
                               "safari",
                               "webkit"
                             ],
-                            $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                            $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                           },
                           {
                             type: "object",
@@ -2657,7 +2657,7 @@ var schemas_default = {
                                   "safari",
                                   "webkit"
                                 ],
-                                $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                               },
                               explicit: {
                                 type: "boolean",
@@ -2833,7 +2833,7 @@ var schemas_default = {
                   ]
                 },
                 device: {
-                  description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android`). Same shape as `startSurface.device`.",
+                  description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`). Same shape as `startSurface.device`.",
                   examples: [
                     "pixel7",
                     {
@@ -2872,7 +2872,7 @@ var schemas_default = {
                           transform: [
                             "trim"
                           ],
-                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                         },
                         deviceType: {
                           type: "string",
@@ -2885,11 +2885,11 @@ var schemas_default = {
                         osVersion: {
                           type: "string",
                           minLength: 1,
-                          description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                          description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                         },
                         headless: {
                           type: "boolean",
-                          description: "Run the Android emulator without a window. Ignored where not applicable."
+                          description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                         },
                         orientation: {
                           type: "string",
@@ -2943,7 +2943,7 @@ var schemas_default = {
                       "safari",
                       "webkit"
                     ],
-                    $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                    $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                   },
                   browser: {
                     type: "object",
@@ -2962,7 +2962,7 @@ var schemas_default = {
                           "safari",
                           "webkit"
                         ],
-                        $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                        $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                       },
                       explicit: {
                         type: "boolean",
@@ -3102,6 +3102,26 @@ var schemas_default = {
                       }
                     }
                   ]
+                },
+                {
+                  platforms: "android"
+                },
+                {
+                  platforms: [
+                    "windows",
+                    "mac",
+                    "android",
+                    "ios"
+                  ],
+                  browsers: "chrome"
+                },
+                {
+                  platforms: "ios",
+                  browsers: "safari",
+                  device: {
+                    name: "test-iphone",
+                    deviceType: "phone"
+                  }
                 }
               ]
             }
@@ -38838,7 +38858,7 @@ var schemas_default = {
                                                 startSurface: {
                                                   $schema: "http://json-schema.org/draft-07/schema#",
                                                   title: "startSurface",
-                                                  description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                                                  description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                                                   components: {
                                                     schemas: {
                                                       appDescriptor: {
@@ -38890,15 +38910,15 @@ var schemas_default = {
                                                           install: {
                                                             type: "string",
                                                             minLength: 1,
-                                                            description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                                            description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                                           },
                                                           activity: {
                                                             type: "string",
                                                             minLength: 1,
-                                                            description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                                            description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                                           },
                                                           device: {
-                                                            description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                                            description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                                             anyOf: [
                                                               {
                                                                 type: "string",
@@ -38931,7 +38951,7 @@ var schemas_default = {
                                                                         transform: [
                                                                           "trim"
                                                                         ],
-                                                                        description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                                        description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                                       },
                                                                       deviceType: {
                                                                         type: "string",
@@ -38944,11 +38964,11 @@ var schemas_default = {
                                                                       osVersion: {
                                                                         type: "string",
                                                                         minLength: 1,
-                                                                        description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                                        description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                                       },
                                                                       headless: {
                                                                         type: "boolean",
-                                                                        description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                                        description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                                       },
                                                                       orientation: {
                                                                         type: "string",
@@ -39120,7 +39140,7 @@ var schemas_default = {
                                                             transform: [
                                                               "trim"
                                                             ],
-                                                            description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                            description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                           },
                                                           deviceType: {
                                                             type: "string",
@@ -39133,11 +39153,11 @@ var schemas_default = {
                                                           osVersion: {
                                                             type: "string",
                                                             minLength: 1,
-                                                            description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                            description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                           },
                                                           headless: {
                                                             type: "boolean",
-                                                            description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                            description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                           },
                                                           orientation: {
                                                             type: "string",
@@ -39236,15 +39256,15 @@ var schemas_default = {
                                                     install: {
                                                       type: "string",
                                                       minLength: 1,
-                                                      description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                                      description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                                     },
                                                     activity: {
                                                       type: "string",
                                                       minLength: 1,
-                                                      description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                                      description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                                     },
                                                     device: {
-                                                      description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                                      description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                                       anyOf: [
                                                         {
                                                           type: "string",
@@ -39277,7 +39297,7 @@ var schemas_default = {
                                                                   transform: [
                                                                     "trim"
                                                                   ],
-                                                                  description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                                  description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                                 },
                                                                 deviceType: {
                                                                   type: "string",
@@ -39290,11 +39310,11 @@ var schemas_default = {
                                                                 osVersion: {
                                                                   type: "string",
                                                                   minLength: 1,
-                                                                  description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                                  description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                                 },
                                                                 headless: {
                                                                   type: "boolean",
-                                                                  description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                                  description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                                 },
                                                                 orientation: {
                                                                   type: "string",
@@ -81029,7 +81049,7 @@ var schemas_default = {
                                   startSurface: {
                                     $schema: "http://json-schema.org/draft-07/schema#",
                                     title: "startSurface",
-                                    description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                                    description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                                     components: {
                                       schemas: {
                                         appDescriptor: {
@@ -81081,15 +81101,15 @@ var schemas_default = {
                                             install: {
                                               type: "string",
                                               minLength: 1,
-                                              description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                              description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                             },
                                             activity: {
                                               type: "string",
                                               minLength: 1,
-                                              description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                              description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                             },
                                             device: {
-                                              description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                              description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                               anyOf: [
                                                 {
                                                   type: "string",
@@ -81122,7 +81142,7 @@ var schemas_default = {
                                                           transform: [
                                                             "trim"
                                                           ],
-                                                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                         },
                                                         deviceType: {
                                                           type: "string",
@@ -81135,11 +81155,11 @@ var schemas_default = {
                                                         osVersion: {
                                                           type: "string",
                                                           minLength: 1,
-                                                          description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                          description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                         },
                                                         headless: {
                                                           type: "boolean",
-                                                          description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                          description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                         },
                                                         orientation: {
                                                           type: "string",
@@ -81311,7 +81331,7 @@ var schemas_default = {
                                               transform: [
                                                 "trim"
                                               ],
-                                              description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                              description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                             },
                                             deviceType: {
                                               type: "string",
@@ -81324,11 +81344,11 @@ var schemas_default = {
                                             osVersion: {
                                               type: "string",
                                               minLength: 1,
-                                              description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                              description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                             },
                                             headless: {
                                               type: "boolean",
-                                              description: "Run the Android emulator without a window. Ignored where not applicable."
+                                              description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                             },
                                             orientation: {
                                               type: "string",
@@ -81427,15 +81447,15 @@ var schemas_default = {
                                       install: {
                                         type: "string",
                                         minLength: 1,
-                                        description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                        description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                       },
                                       activity: {
                                         type: "string",
                                         minLength: 1,
-                                        description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                        description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                       },
                                       device: {
-                                        description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                        description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                         anyOf: [
                                           {
                                             type: "string",
@@ -81468,7 +81488,7 @@ var schemas_default = {
                                                     transform: [
                                                       "trim"
                                                     ],
-                                                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                   },
                                                   deviceType: {
                                                     type: "string",
@@ -81481,11 +81501,11 @@ var schemas_default = {
                                                   osVersion: {
                                                     type: "string",
                                                     minLength: 1,
-                                                    description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                    description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                   },
                                                   headless: {
                                                     type: "boolean",
-                                                    description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                    description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                   },
                                                   orientation: {
                                                     type: "string",
@@ -87119,7 +87139,7 @@ var schemas_default = {
         ]
       },
       browsers: {
-        description: "Browsers to run tests on.",
+        description: "Browsers to run tests on. On a mobile (`android`/`ios`) platform entry, the browser runs on the managed device: `chrome` on Android, `safari` on iOS (other combinations skip the context), and it fills in automatically when omitted. Device browsers don't take desktop display config: authored `window`/`viewport` dimensions and `headless: false` are rejected on mobile entries (the device owns its display \u2014 control it via the device descriptor's `headless`/`deviceType`); `headless: true` matches this schema's default and is ignored.",
         anyOf: [
           {
             type: "string",
@@ -87130,7 +87150,7 @@ var schemas_default = {
               "safari",
               "webkit"
             ],
-            $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+            $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
           },
           {
             type: "object",
@@ -87149,7 +87169,7 @@ var schemas_default = {
                   "safari",
                   "webkit"
                 ],
-                $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
               },
               explicit: {
                 type: "boolean",
@@ -87209,7 +87229,7 @@ var schemas_default = {
                     "safari",
                     "webkit"
                   ],
-                  $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                  $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                 },
                 {
                   type: "object",
@@ -87228,7 +87248,7 @@ var schemas_default = {
                         "safari",
                         "webkit"
                       ],
-                      $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                      $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                     },
                     explicit: {
                       type: "boolean",
@@ -87404,7 +87424,7 @@ var schemas_default = {
         ]
       },
       device: {
-        description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android`). Same shape as `startSurface.device`.",
+        description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`). Same shape as `startSurface.device`.",
         examples: [
           "pixel7",
           {
@@ -87443,7 +87463,7 @@ var schemas_default = {
                 transform: [
                   "trim"
                 ],
-                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
               },
               deviceType: {
                 type: "string",
@@ -87456,11 +87476,11 @@ var schemas_default = {
               osVersion: {
                 type: "string",
                 minLength: 1,
-                description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
               },
               headless: {
                 type: "boolean",
-                description: "Run the Android emulator without a window. Ignored where not applicable."
+                description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
               },
               orientation: {
                 type: "string",
@@ -87514,7 +87534,7 @@ var schemas_default = {
             "safari",
             "webkit"
           ],
-          $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+          $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
         },
         browser: {
           type: "object",
@@ -87533,7 +87553,7 @@ var schemas_default = {
                 "safari",
                 "webkit"
               ],
-              $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+              $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
             },
             explicit: {
               type: "boolean",
@@ -87673,6 +87693,26 @@ var schemas_default = {
             }
           }
         ]
+      },
+      {
+        platforms: "android"
+      },
+      {
+        platforms: [
+          "windows",
+          "mac",
+          "android",
+          "ios"
+        ],
+        browsers: "chrome"
+      },
+      {
+        platforms: "ios",
+        browsers: "safari",
+        device: {
+          name: "test-iphone",
+          deviceType: "phone"
+        }
       }
     ]
   },
@@ -100010,7 +100050,7 @@ var schemas_default = {
                       ]
                     },
                     browsers: {
-                      description: "Browsers to run tests on.",
+                      description: "Browsers to run tests on. On a mobile (`android`/`ios`) platform entry, the browser runs on the managed device: `chrome` on Android, `safari` on iOS (other combinations skip the context), and it fills in automatically when omitted. Device browsers don't take desktop display config: authored `window`/`viewport` dimensions and `headless: false` are rejected on mobile entries (the device owns its display \u2014 control it via the device descriptor's `headless`/`deviceType`); `headless: true` matches this schema's default and is ignored.",
                       anyOf: [
                         {
                           type: "string",
@@ -100021,7 +100061,7 @@ var schemas_default = {
                             "safari",
                             "webkit"
                           ],
-                          $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                          $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                         },
                         {
                           type: "object",
@@ -100040,7 +100080,7 @@ var schemas_default = {
                                 "safari",
                                 "webkit"
                               ],
-                              $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                              $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                             },
                             explicit: {
                               type: "boolean",
@@ -100100,7 +100140,7 @@ var schemas_default = {
                                   "safari",
                                   "webkit"
                                 ],
-                                $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                               },
                               {
                                 type: "object",
@@ -100119,7 +100159,7 @@ var schemas_default = {
                                       "safari",
                                       "webkit"
                                     ],
-                                    $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                    $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                   },
                                   explicit: {
                                     type: "boolean",
@@ -100295,7 +100335,7 @@ var schemas_default = {
                       ]
                     },
                     device: {
-                      description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android`). Same shape as `startSurface.device`.",
+                      description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`). Same shape as `startSurface.device`.",
                       examples: [
                         "pixel7",
                         {
@@ -100334,7 +100374,7 @@ var schemas_default = {
                               transform: [
                                 "trim"
                               ],
-                              description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                              description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                             },
                             deviceType: {
                               type: "string",
@@ -100347,11 +100387,11 @@ var schemas_default = {
                             osVersion: {
                               type: "string",
                               minLength: 1,
-                              description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                              description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                             },
                             headless: {
                               type: "boolean",
-                              description: "Run the Android emulator without a window. Ignored where not applicable."
+                              description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                             },
                             orientation: {
                               type: "string",
@@ -100405,7 +100445,7 @@ var schemas_default = {
                           "safari",
                           "webkit"
                         ],
-                        $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                        $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                       },
                       browser: {
                         type: "object",
@@ -100424,7 +100464,7 @@ var schemas_default = {
                               "safari",
                               "webkit"
                             ],
-                            $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                            $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                           },
                           explicit: {
                             type: "boolean",
@@ -100564,6 +100604,26 @@ var schemas_default = {
                           }
                         }
                       ]
+                    },
+                    {
+                      platforms: "android"
+                    },
+                    {
+                      platforms: [
+                        "windows",
+                        "mac",
+                        "android",
+                        "ios"
+                      ],
+                      browsers: "chrome"
+                    },
+                    {
+                      platforms: "ios",
+                      browsers: "safari",
+                      device: {
+                        name: "test-iphone",
+                        deviceType: "phone"
+                      }
                     }
                   ]
                 }
@@ -136300,7 +136360,7 @@ var schemas_default = {
                                                     startSurface: {
                                                       $schema: "http://json-schema.org/draft-07/schema#",
                                                       title: "startSurface",
-                                                      description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                                                      description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                                                       components: {
                                                         schemas: {
                                                           appDescriptor: {
@@ -136352,15 +136412,15 @@ var schemas_default = {
                                                               install: {
                                                                 type: "string",
                                                                 minLength: 1,
-                                                                description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                                                description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                                               },
                                                               activity: {
                                                                 type: "string",
                                                                 minLength: 1,
-                                                                description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                                                description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                                               },
                                                               device: {
-                                                                description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                                                description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                                                 anyOf: [
                                                                   {
                                                                     type: "string",
@@ -136393,7 +136453,7 @@ var schemas_default = {
                                                                             transform: [
                                                                               "trim"
                                                                             ],
-                                                                            description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                                            description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                                           },
                                                                           deviceType: {
                                                                             type: "string",
@@ -136406,11 +136466,11 @@ var schemas_default = {
                                                                           osVersion: {
                                                                             type: "string",
                                                                             minLength: 1,
-                                                                            description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                                            description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                                           },
                                                                           headless: {
                                                                             type: "boolean",
-                                                                            description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                                            description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                                           },
                                                                           orientation: {
                                                                             type: "string",
@@ -136582,7 +136642,7 @@ var schemas_default = {
                                                                 transform: [
                                                                   "trim"
                                                                 ],
-                                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                               },
                                                               deviceType: {
                                                                 type: "string",
@@ -136595,11 +136655,11 @@ var schemas_default = {
                                                               osVersion: {
                                                                 type: "string",
                                                                 minLength: 1,
-                                                                description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                                description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                               },
                                                               headless: {
                                                                 type: "boolean",
-                                                                description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                                description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                               },
                                                               orientation: {
                                                                 type: "string",
@@ -136698,15 +136758,15 @@ var schemas_default = {
                                                         install: {
                                                           type: "string",
                                                           minLength: 1,
-                                                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                                         },
                                                         activity: {
                                                           type: "string",
                                                           minLength: 1,
-                                                          description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                                          description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                                         },
                                                         device: {
-                                                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                                           anyOf: [
                                                             {
                                                               type: "string",
@@ -136739,7 +136799,7 @@ var schemas_default = {
                                                                       transform: [
                                                                         "trim"
                                                                       ],
-                                                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                                     },
                                                                     deviceType: {
                                                                       type: "string",
@@ -136752,11 +136812,11 @@ var schemas_default = {
                                                                     osVersion: {
                                                                       type: "string",
                                                                       minLength: 1,
-                                                                      description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                                      description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                                     },
                                                                     headless: {
                                                                       type: "boolean",
-                                                                      description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                                      description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                                     },
                                                                     orientation: {
                                                                       type: "string",
@@ -178491,7 +178551,7 @@ var schemas_default = {
                                       startSurface: {
                                         $schema: "http://json-schema.org/draft-07/schema#",
                                         title: "startSurface",
-                                        description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                                        description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                                         components: {
                                           schemas: {
                                             appDescriptor: {
@@ -178543,15 +178603,15 @@ var schemas_default = {
                                                 install: {
                                                   type: "string",
                                                   minLength: 1,
-                                                  description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                                  description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                                 },
                                                 activity: {
                                                   type: "string",
                                                   minLength: 1,
-                                                  description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                                  description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                                 },
                                                 device: {
-                                                  description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                                  description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                                   anyOf: [
                                                     {
                                                       type: "string",
@@ -178584,7 +178644,7 @@ var schemas_default = {
                                                               transform: [
                                                                 "trim"
                                                               ],
-                                                              description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                              description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                             },
                                                             deviceType: {
                                                               type: "string",
@@ -178597,11 +178657,11 @@ var schemas_default = {
                                                             osVersion: {
                                                               type: "string",
                                                               minLength: 1,
-                                                              description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                              description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                             },
                                                             headless: {
                                                               type: "boolean",
-                                                              description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                              description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                             },
                                                             orientation: {
                                                               type: "string",
@@ -178773,7 +178833,7 @@ var schemas_default = {
                                                   transform: [
                                                     "trim"
                                                   ],
-                                                  description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                  description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                 },
                                                 deviceType: {
                                                   type: "string",
@@ -178786,11 +178846,11 @@ var schemas_default = {
                                                 osVersion: {
                                                   type: "string",
                                                   minLength: 1,
-                                                  description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                  description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                 },
                                                 headless: {
                                                   type: "boolean",
-                                                  description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                  description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                 },
                                                 orientation: {
                                                   type: "string",
@@ -178889,15 +178949,15 @@ var schemas_default = {
                                           install: {
                                             type: "string",
                                             minLength: 1,
-                                            description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                            description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                           },
                                           activity: {
                                             type: "string",
                                             minLength: 1,
-                                            description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                            description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                           },
                                           device: {
-                                            description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                            description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                             anyOf: [
                                               {
                                                 type: "string",
@@ -178930,7 +178990,7 @@ var schemas_default = {
                                                         transform: [
                                                           "trim"
                                                         ],
-                                                        description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                        description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                       },
                                                       deviceType: {
                                                         type: "string",
@@ -178943,11 +179003,11 @@ var schemas_default = {
                                                       osVersion: {
                                                         type: "string",
                                                         minLength: 1,
-                                                        description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                        description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                       },
                                                       headless: {
                                                         type: "boolean",
-                                                        description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                        description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                       },
                                                       orientation: {
                                                         type: "string",
@@ -184643,7 +184703,7 @@ var schemas_default = {
                             ]
                           },
                           browsers: {
-                            description: "Browsers to run tests on.",
+                            description: "Browsers to run tests on. On a mobile (`android`/`ios`) platform entry, the browser runs on the managed device: `chrome` on Android, `safari` on iOS (other combinations skip the context), and it fills in automatically when omitted. Device browsers don't take desktop display config: authored `window`/`viewport` dimensions and `headless: false` are rejected on mobile entries (the device owns its display \u2014 control it via the device descriptor's `headless`/`deviceType`); `headless: true` matches this schema's default and is ignored.",
                             anyOf: [
                               {
                                 type: "string",
@@ -184654,7 +184714,7 @@ var schemas_default = {
                                   "safari",
                                   "webkit"
                                 ],
-                                $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                               },
                               {
                                 type: "object",
@@ -184673,7 +184733,7 @@ var schemas_default = {
                                       "safari",
                                       "webkit"
                                     ],
-                                    $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                    $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                   },
                                   explicit: {
                                     type: "boolean",
@@ -184733,7 +184793,7 @@ var schemas_default = {
                                         "safari",
                                         "webkit"
                                       ],
-                                      $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                      $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                     },
                                     {
                                       type: "object",
@@ -184752,7 +184812,7 @@ var schemas_default = {
                                             "safari",
                                             "webkit"
                                           ],
-                                          $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                          $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                         },
                                         explicit: {
                                           type: "boolean",
@@ -184928,7 +184988,7 @@ var schemas_default = {
                             ]
                           },
                           device: {
-                            description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android`). Same shape as `startSurface.device`.",
+                            description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`). Same shape as `startSurface.device`.",
                             examples: [
                               "pixel7",
                               {
@@ -184967,7 +185027,7 @@ var schemas_default = {
                                     transform: [
                                       "trim"
                                     ],
-                                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                   },
                                   deviceType: {
                                     type: "string",
@@ -184980,11 +185040,11 @@ var schemas_default = {
                                   osVersion: {
                                     type: "string",
                                     minLength: 1,
-                                    description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                    description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                   },
                                   headless: {
                                     type: "boolean",
-                                    description: "Run the Android emulator without a window. Ignored where not applicable."
+                                    description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                   },
                                   orientation: {
                                     type: "string",
@@ -185038,7 +185098,7 @@ var schemas_default = {
                                 "safari",
                                 "webkit"
                               ],
-                              $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                              $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                             },
                             browser: {
                               type: "object",
@@ -185057,7 +185117,7 @@ var schemas_default = {
                                     "safari",
                                     "webkit"
                                   ],
-                                  $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                  $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                 },
                                 explicit: {
                                   type: "boolean",
@@ -185197,6 +185257,26 @@ var schemas_default = {
                                 }
                               }
                             ]
+                          },
+                          {
+                            platforms: "android"
+                          },
+                          {
+                            platforms: [
+                              "windows",
+                              "mac",
+                              "android",
+                              "ios"
+                            ],
+                            browsers: "chrome"
+                          },
+                          {
+                            platforms: "ios",
+                            browsers: "safari",
+                            device: {
+                              name: "test-iphone",
+                              deviceType: "phone"
+                            }
                           }
                         ]
                       }
@@ -185485,7 +185565,7 @@ var schemas_default = {
                                       ]
                                     },
                                     browsers: {
-                                      description: "Browsers to run tests on.",
+                                      description: "Browsers to run tests on. On a mobile (`android`/`ios`) platform entry, the browser runs on the managed device: `chrome` on Android, `safari` on iOS (other combinations skip the context), and it fills in automatically when omitted. Device browsers don't take desktop display config: authored `window`/`viewport` dimensions and `headless: false` are rejected on mobile entries (the device owns its display \u2014 control it via the device descriptor's `headless`/`deviceType`); `headless: true` matches this schema's default and is ignored.",
                                       anyOf: [
                                         {
                                           type: "string",
@@ -185496,7 +185576,7 @@ var schemas_default = {
                                             "safari",
                                             "webkit"
                                           ],
-                                          $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                          $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                         },
                                         {
                                           type: "object",
@@ -185515,7 +185595,7 @@ var schemas_default = {
                                                 "safari",
                                                 "webkit"
                                               ],
-                                              $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                              $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                             },
                                             explicit: {
                                               type: "boolean",
@@ -185575,7 +185655,7 @@ var schemas_default = {
                                                   "safari",
                                                   "webkit"
                                                 ],
-                                                $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                                $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                               },
                                               {
                                                 type: "object",
@@ -185594,7 +185674,7 @@ var schemas_default = {
                                                       "safari",
                                                       "webkit"
                                                     ],
-                                                    $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                                    $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                                   },
                                                   explicit: {
                                                     type: "boolean",
@@ -185770,7 +185850,7 @@ var schemas_default = {
                                       ]
                                     },
                                     device: {
-                                      description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android`). Same shape as `startSurface.device`.",
+                                      description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`). Same shape as `startSurface.device`.",
                                       examples: [
                                         "pixel7",
                                         {
@@ -185809,7 +185889,7 @@ var schemas_default = {
                                               transform: [
                                                 "trim"
                                               ],
-                                              description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                              description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                             },
                                             deviceType: {
                                               type: "string",
@@ -185822,11 +185902,11 @@ var schemas_default = {
                                             osVersion: {
                                               type: "string",
                                               minLength: 1,
-                                              description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                              description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                             },
                                             headless: {
                                               type: "boolean",
-                                              description: "Run the Android emulator without a window. Ignored where not applicable."
+                                              description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                             },
                                             orientation: {
                                               type: "string",
@@ -185880,7 +185960,7 @@ var schemas_default = {
                                           "safari",
                                           "webkit"
                                         ],
-                                        $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                        $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                       },
                                       browser: {
                                         type: "object",
@@ -185899,7 +185979,7 @@ var schemas_default = {
                                               "safari",
                                               "webkit"
                                             ],
-                                            $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                            $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                           },
                                           explicit: {
                                             type: "boolean",
@@ -186039,6 +186119,26 @@ var schemas_default = {
                                           }
                                         }
                                       ]
+                                    },
+                                    {
+                                      platforms: "android"
+                                    },
+                                    {
+                                      platforms: [
+                                        "windows",
+                                        "mac",
+                                        "android",
+                                        "ios"
+                                      ],
+                                      browsers: "chrome"
+                                    },
+                                    {
+                                      platforms: "ios",
+                                      browsers: "safari",
+                                      device: {
+                                        name: "test-iphone",
+                                        deviceType: "phone"
+                                      }
                                     }
                                   ]
                                 }
@@ -222415,7 +222515,7 @@ var schemas_default = {
                                         startSurface: {
                                           $schema: "http://json-schema.org/draft-07/schema#",
                                           title: "startSurface",
-                                          description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                                          description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                                           components: {
                                             schemas: {
                                               appDescriptor: {
@@ -222467,15 +222567,15 @@ var schemas_default = {
                                                   install: {
                                                     type: "string",
                                                     minLength: 1,
-                                                    description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                                    description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                                   },
                                                   activity: {
                                                     type: "string",
                                                     minLength: 1,
-                                                    description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                                    description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                                   },
                                                   device: {
-                                                    description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                                    description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                                     anyOf: [
                                                       {
                                                         type: "string",
@@ -222508,7 +222608,7 @@ var schemas_default = {
                                                                 transform: [
                                                                   "trim"
                                                                 ],
-                                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                               },
                                                               deviceType: {
                                                                 type: "string",
@@ -222521,11 +222621,11 @@ var schemas_default = {
                                                               osVersion: {
                                                                 type: "string",
                                                                 minLength: 1,
-                                                                description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                                description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                               },
                                                               headless: {
                                                                 type: "boolean",
-                                                                description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                                description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                               },
                                                               orientation: {
                                                                 type: "string",
@@ -222697,7 +222797,7 @@ var schemas_default = {
                                                     transform: [
                                                       "trim"
                                                     ],
-                                                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                   },
                                                   deviceType: {
                                                     type: "string",
@@ -222710,11 +222810,11 @@ var schemas_default = {
                                                   osVersion: {
                                                     type: "string",
                                                     minLength: 1,
-                                                    description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                    description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                   },
                                                   headless: {
                                                     type: "boolean",
-                                                    description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                    description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                   },
                                                   orientation: {
                                                     type: "string",
@@ -222813,15 +222913,15 @@ var schemas_default = {
                                             install: {
                                               type: "string",
                                               minLength: 1,
-                                              description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                              description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                             },
                                             activity: {
                                               type: "string",
                                               minLength: 1,
-                                              description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                              description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                             },
                                             device: {
-                                              description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                              description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                               anyOf: [
                                                 {
                                                   type: "string",
@@ -222854,7 +222954,7 @@ var schemas_default = {
                                                           transform: [
                                                             "trim"
                                                           ],
-                                                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                         },
                                                         deviceType: {
                                                           type: "string",
@@ -222867,11 +222967,11 @@ var schemas_default = {
                                                         osVersion: {
                                                           type: "string",
                                                           minLength: 1,
-                                                          description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                          description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                         },
                                                         headless: {
                                                           type: "boolean",
-                                                          description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                          description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                         },
                                                         orientation: {
                                                           type: "string",
@@ -228200,7 +228300,7 @@ var schemas_default = {
                                         "safari",
                                         "webkit"
                                       ],
-                                      $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                      $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                     },
                                     explicit: {
                                       type: "boolean",
@@ -263905,7 +264005,7 @@ var schemas_default = {
                                               startSurface: {
                                                 $schema: "http://json-schema.org/draft-07/schema#",
                                                 title: "startSurface",
-                                                description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                                                description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                                                 components: {
                                                   schemas: {
                                                     appDescriptor: {
@@ -263957,15 +264057,15 @@ var schemas_default = {
                                                         install: {
                                                           type: "string",
                                                           minLength: 1,
-                                                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                                         },
                                                         activity: {
                                                           type: "string",
                                                           minLength: 1,
-                                                          description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                                          description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                                         },
                                                         device: {
-                                                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                                           anyOf: [
                                                             {
                                                               type: "string",
@@ -263998,7 +264098,7 @@ var schemas_default = {
                                                                       transform: [
                                                                         "trim"
                                                                       ],
-                                                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                                     },
                                                                     deviceType: {
                                                                       type: "string",
@@ -264011,11 +264111,11 @@ var schemas_default = {
                                                                     osVersion: {
                                                                       type: "string",
                                                                       minLength: 1,
-                                                                      description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                                      description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                                     },
                                                                     headless: {
                                                                       type: "boolean",
-                                                                      description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                                      description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                                     },
                                                                     orientation: {
                                                                       type: "string",
@@ -264187,7 +264287,7 @@ var schemas_default = {
                                                           transform: [
                                                             "trim"
                                                           ],
-                                                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                         },
                                                         deviceType: {
                                                           type: "string",
@@ -264200,11 +264300,11 @@ var schemas_default = {
                                                         osVersion: {
                                                           type: "string",
                                                           minLength: 1,
-                                                          description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                          description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                         },
                                                         headless: {
                                                           type: "boolean",
-                                                          description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                          description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                         },
                                                         orientation: {
                                                           type: "string",
@@ -264303,15 +264403,15 @@ var schemas_default = {
                                                   install: {
                                                     type: "string",
                                                     minLength: 1,
-                                                    description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                                    description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                                   },
                                                   activity: {
                                                     type: "string",
                                                     minLength: 1,
-                                                    description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                                    description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                                   },
                                                   device: {
-                                                    description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                                    description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                                     anyOf: [
                                                       {
                                                         type: "string",
@@ -264344,7 +264444,7 @@ var schemas_default = {
                                                                 transform: [
                                                                   "trim"
                                                                 ],
-                                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                               },
                                                               deviceType: {
                                                                 type: "string",
@@ -264357,11 +264457,11 @@ var schemas_default = {
                                                               osVersion: {
                                                                 type: "string",
                                                                 minLength: 1,
-                                                                description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                                description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                               },
                                                               headless: {
                                                                 type: "boolean",
-                                                                description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                                description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                               },
                                                               orientation: {
                                                                 type: "string",
@@ -270544,7 +270644,7 @@ var schemas_default = {
                             ]
                           },
                           browsers: {
-                            description: "Browsers to run tests on.",
+                            description: "Browsers to run tests on. On a mobile (`android`/`ios`) platform entry, the browser runs on the managed device: `chrome` on Android, `safari` on iOS (other combinations skip the context), and it fills in automatically when omitted. Device browsers don't take desktop display config: authored `window`/`viewport` dimensions and `headless: false` are rejected on mobile entries (the device owns its display \u2014 control it via the device descriptor's `headless`/`deviceType`); `headless: true` matches this schema's default and is ignored.",
                             anyOf: [
                               {
                                 type: "string",
@@ -270555,7 +270655,7 @@ var schemas_default = {
                                   "safari",
                                   "webkit"
                                 ],
-                                $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                               },
                               {
                                 type: "object",
@@ -270574,7 +270674,7 @@ var schemas_default = {
                                       "safari",
                                       "webkit"
                                     ],
-                                    $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                    $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                   },
                                   explicit: {
                                     type: "boolean",
@@ -270634,7 +270734,7 @@ var schemas_default = {
                                         "safari",
                                         "webkit"
                                       ],
-                                      $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                      $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                     },
                                     {
                                       type: "object",
@@ -270653,7 +270753,7 @@ var schemas_default = {
                                             "safari",
                                             "webkit"
                                           ],
-                                          $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                          $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                         },
                                         explicit: {
                                           type: "boolean",
@@ -270829,7 +270929,7 @@ var schemas_default = {
                             ]
                           },
                           device: {
-                            description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android`). Same shape as `startSurface.device`.",
+                            description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`). Same shape as `startSurface.device`.",
                             examples: [
                               "pixel7",
                               {
@@ -270868,7 +270968,7 @@ var schemas_default = {
                                     transform: [
                                       "trim"
                                     ],
-                                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                   },
                                   deviceType: {
                                     type: "string",
@@ -270881,11 +270981,11 @@ var schemas_default = {
                                   osVersion: {
                                     type: "string",
                                     minLength: 1,
-                                    description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                    description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                   },
                                   headless: {
                                     type: "boolean",
-                                    description: "Run the Android emulator without a window. Ignored where not applicable."
+                                    description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                   },
                                   orientation: {
                                     type: "string",
@@ -270939,7 +271039,7 @@ var schemas_default = {
                                 "safari",
                                 "webkit"
                               ],
-                              $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                              $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                             },
                             browser: {
                               type: "object",
@@ -270958,7 +271058,7 @@ var schemas_default = {
                                     "safari",
                                     "webkit"
                                   ],
-                                  $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                  $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                 },
                                 explicit: {
                                   type: "boolean",
@@ -271098,6 +271198,26 @@ var schemas_default = {
                                 }
                               }
                             ]
+                          },
+                          {
+                            platforms: "android"
+                          },
+                          {
+                            platforms: [
+                              "windows",
+                              "mac",
+                              "android",
+                              "ios"
+                            ],
+                            browsers: "chrome"
+                          },
+                          {
+                            platforms: "ios",
+                            browsers: "safari",
+                            device: {
+                              name: "test-iphone",
+                              deviceType: "phone"
+                            }
                           }
                         ]
                       }
@@ -271386,7 +271506,7 @@ var schemas_default = {
                                       ]
                                     },
                                     browsers: {
-                                      description: "Browsers to run tests on.",
+                                      description: "Browsers to run tests on. On a mobile (`android`/`ios`) platform entry, the browser runs on the managed device: `chrome` on Android, `safari` on iOS (other combinations skip the context), and it fills in automatically when omitted. Device browsers don't take desktop display config: authored `window`/`viewport` dimensions and `headless: false` are rejected on mobile entries (the device owns its display \u2014 control it via the device descriptor's `headless`/`deviceType`); `headless: true` matches this schema's default and is ignored.",
                                       anyOf: [
                                         {
                                           type: "string",
@@ -271397,7 +271517,7 @@ var schemas_default = {
                                             "safari",
                                             "webkit"
                                           ],
-                                          $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                          $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                         },
                                         {
                                           type: "object",
@@ -271416,7 +271536,7 @@ var schemas_default = {
                                                 "safari",
                                                 "webkit"
                                               ],
-                                              $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                              $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                             },
                                             explicit: {
                                               type: "boolean",
@@ -271476,7 +271596,7 @@ var schemas_default = {
                                                   "safari",
                                                   "webkit"
                                                 ],
-                                                $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                                $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                               },
                                               {
                                                 type: "object",
@@ -271495,7 +271615,7 @@ var schemas_default = {
                                                       "safari",
                                                       "webkit"
                                                     ],
-                                                    $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                                    $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                                   },
                                                   explicit: {
                                                     type: "boolean",
@@ -271671,7 +271791,7 @@ var schemas_default = {
                                       ]
                                     },
                                     device: {
-                                      description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android`). Same shape as `startSurface.device`.",
+                                      description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`). Same shape as `startSurface.device`.",
                                       examples: [
                                         "pixel7",
                                         {
@@ -271710,7 +271830,7 @@ var schemas_default = {
                                               transform: [
                                                 "trim"
                                               ],
-                                              description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                              description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                             },
                                             deviceType: {
                                               type: "string",
@@ -271723,11 +271843,11 @@ var schemas_default = {
                                             osVersion: {
                                               type: "string",
                                               minLength: 1,
-                                              description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                              description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                             },
                                             headless: {
                                               type: "boolean",
-                                              description: "Run the Android emulator without a window. Ignored where not applicable."
+                                              description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                             },
                                             orientation: {
                                               type: "string",
@@ -271781,7 +271901,7 @@ var schemas_default = {
                                           "safari",
                                           "webkit"
                                         ],
-                                        $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                        $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                       },
                                       browser: {
                                         type: "object",
@@ -271800,7 +271920,7 @@ var schemas_default = {
                                               "safari",
                                               "webkit"
                                             ],
-                                            $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                            $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                           },
                                           explicit: {
                                             type: "boolean",
@@ -271940,6 +272060,26 @@ var schemas_default = {
                                           }
                                         }
                                       ]
+                                    },
+                                    {
+                                      platforms: "android"
+                                    },
+                                    {
+                                      platforms: [
+                                        "windows",
+                                        "mac",
+                                        "android",
+                                        "ios"
+                                      ],
+                                      browsers: "chrome"
+                                    },
+                                    {
+                                      platforms: "ios",
+                                      browsers: "safari",
+                                      device: {
+                                        name: "test-iphone",
+                                        deviceType: "phone"
+                                      }
                                     }
                                   ]
                                 }
@@ -308316,7 +308456,7 @@ var schemas_default = {
                                         startSurface: {
                                           $schema: "http://json-schema.org/draft-07/schema#",
                                           title: "startSurface",
-                                          description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                                          description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                                           components: {
                                             schemas: {
                                               appDescriptor: {
@@ -308368,15 +308508,15 @@ var schemas_default = {
                                                   install: {
                                                     type: "string",
                                                     minLength: 1,
-                                                    description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                                    description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                                   },
                                                   activity: {
                                                     type: "string",
                                                     minLength: 1,
-                                                    description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                                    description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                                   },
                                                   device: {
-                                                    description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                                    description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                                     anyOf: [
                                                       {
                                                         type: "string",
@@ -308409,7 +308549,7 @@ var schemas_default = {
                                                                 transform: [
                                                                   "trim"
                                                                 ],
-                                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                               },
                                                               deviceType: {
                                                                 type: "string",
@@ -308422,11 +308562,11 @@ var schemas_default = {
                                                               osVersion: {
                                                                 type: "string",
                                                                 minLength: 1,
-                                                                description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                                description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                               },
                                                               headless: {
                                                                 type: "boolean",
-                                                                description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                                description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                               },
                                                               orientation: {
                                                                 type: "string",
@@ -308598,7 +308738,7 @@ var schemas_default = {
                                                     transform: [
                                                       "trim"
                                                     ],
-                                                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                   },
                                                   deviceType: {
                                                     type: "string",
@@ -308611,11 +308751,11 @@ var schemas_default = {
                                                   osVersion: {
                                                     type: "string",
                                                     minLength: 1,
-                                                    description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                    description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                   },
                                                   headless: {
                                                     type: "boolean",
-                                                    description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                    description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                   },
                                                   orientation: {
                                                     type: "string",
@@ -308714,15 +308854,15 @@ var schemas_default = {
                                             install: {
                                               type: "string",
                                               minLength: 1,
-                                              description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                              description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                             },
                                             activity: {
                                               type: "string",
                                               minLength: 1,
-                                              description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                              description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                             },
                                             device: {
-                                              description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                              description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                               anyOf: [
                                                 {
                                                   type: "string",
@@ -308755,7 +308895,7 @@ var schemas_default = {
                                                           transform: [
                                                             "trim"
                                                           ],
-                                                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                         },
                                                         deviceType: {
                                                           type: "string",
@@ -308768,11 +308908,11 @@ var schemas_default = {
                                                         osVersion: {
                                                           type: "string",
                                                           minLength: 1,
-                                                          description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                          description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                         },
                                                         headless: {
                                                           type: "boolean",
-                                                          description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                          description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                         },
                                                         orientation: {
                                                           type: "string",
@@ -314101,7 +314241,7 @@ var schemas_default = {
                                         "safari",
                                         "webkit"
                                       ],
-                                      $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                      $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                     },
                                     explicit: {
                                       type: "boolean",
@@ -349806,7 +349946,7 @@ var schemas_default = {
                                               startSurface: {
                                                 $schema: "http://json-schema.org/draft-07/schema#",
                                                 title: "startSurface",
-                                                description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                                                description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                                                 components: {
                                                   schemas: {
                                                     appDescriptor: {
@@ -349858,15 +349998,15 @@ var schemas_default = {
                                                         install: {
                                                           type: "string",
                                                           minLength: 1,
-                                                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                                         },
                                                         activity: {
                                                           type: "string",
                                                           minLength: 1,
-                                                          description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                                          description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                                         },
                                                         device: {
-                                                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                                           anyOf: [
                                                             {
                                                               type: "string",
@@ -349899,7 +350039,7 @@ var schemas_default = {
                                                                       transform: [
                                                                         "trim"
                                                                       ],
-                                                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                                     },
                                                                     deviceType: {
                                                                       type: "string",
@@ -349912,11 +350052,11 @@ var schemas_default = {
                                                                     osVersion: {
                                                                       type: "string",
                                                                       minLength: 1,
-                                                                      description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                                      description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                                     },
                                                                     headless: {
                                                                       type: "boolean",
-                                                                      description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                                      description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                                     },
                                                                     orientation: {
                                                                       type: "string",
@@ -350088,7 +350228,7 @@ var schemas_default = {
                                                           transform: [
                                                             "trim"
                                                           ],
-                                                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                         },
                                                         deviceType: {
                                                           type: "string",
@@ -350101,11 +350241,11 @@ var schemas_default = {
                                                         osVersion: {
                                                           type: "string",
                                                           minLength: 1,
-                                                          description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                          description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                         },
                                                         headless: {
                                                           type: "boolean",
-                                                          description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                          description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                         },
                                                         orientation: {
                                                           type: "string",
@@ -350204,15 +350344,15 @@ var schemas_default = {
                                                   install: {
                                                     type: "string",
                                                     minLength: 1,
-                                                    description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                                    description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                                   },
                                                   activity: {
                                                     type: "string",
                                                     minLength: 1,
-                                                    description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                                    description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                                   },
                                                   device: {
-                                                    description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                                    description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                                     anyOf: [
                                                       {
                                                         type: "string",
@@ -350245,7 +350385,7 @@ var schemas_default = {
                                                                 transform: [
                                                                   "trim"
                                                                 ],
-                                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                               },
                                                               deviceType: {
                                                                 type: "string",
@@ -350258,11 +350398,11 @@ var schemas_default = {
                                                               osVersion: {
                                                                 type: "string",
                                                                 minLength: 1,
-                                                                description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                                description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                               },
                                                               headless: {
                                                                 type: "boolean",
-                                                                description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                                description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                               },
                                                               orientation: {
                                                                 type: "string",
@@ -359658,7 +359798,7 @@ var schemas_default = {
                   ]
                 },
                 browsers: {
-                  description: "Browsers to run tests on.",
+                  description: "Browsers to run tests on. On a mobile (`android`/`ios`) platform entry, the browser runs on the managed device: `chrome` on Android, `safari` on iOS (other combinations skip the context), and it fills in automatically when omitted. Device browsers don't take desktop display config: authored `window`/`viewport` dimensions and `headless: false` are rejected on mobile entries (the device owns its display \u2014 control it via the device descriptor's `headless`/`deviceType`); `headless: true` matches this schema's default and is ignored.",
                   anyOf: [
                     {
                       type: "string",
@@ -359669,7 +359809,7 @@ var schemas_default = {
                         "safari",
                         "webkit"
                       ],
-                      $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                      $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                     },
                     {
                       type: "object",
@@ -359688,7 +359828,7 @@ var schemas_default = {
                             "safari",
                             "webkit"
                           ],
-                          $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                          $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                         },
                         explicit: {
                           type: "boolean",
@@ -359748,7 +359888,7 @@ var schemas_default = {
                               "safari",
                               "webkit"
                             ],
-                            $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                            $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                           },
                           {
                             type: "object",
@@ -359767,7 +359907,7 @@ var schemas_default = {
                                   "safari",
                                   "webkit"
                                 ],
-                                $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                               },
                               explicit: {
                                 type: "boolean",
@@ -359943,7 +360083,7 @@ var schemas_default = {
                   ]
                 },
                 device: {
-                  description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android`). Same shape as `startSurface.device`.",
+                  description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`). Same shape as `startSurface.device`.",
                   examples: [
                     "pixel7",
                     {
@@ -359982,7 +360122,7 @@ var schemas_default = {
                           transform: [
                             "trim"
                           ],
-                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                         },
                         deviceType: {
                           type: "string",
@@ -359995,11 +360135,11 @@ var schemas_default = {
                         osVersion: {
                           type: "string",
                           minLength: 1,
-                          description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                          description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                         },
                         headless: {
                           type: "boolean",
-                          description: "Run the Android emulator without a window. Ignored where not applicable."
+                          description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                         },
                         orientation: {
                           type: "string",
@@ -360053,7 +360193,7 @@ var schemas_default = {
                       "safari",
                       "webkit"
                     ],
-                    $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                    $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                   },
                   browser: {
                     type: "object",
@@ -360072,7 +360212,7 @@ var schemas_default = {
                           "safari",
                           "webkit"
                         ],
-                        $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                        $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                       },
                       explicit: {
                         type: "boolean",
@@ -360212,6 +360352,26 @@ var schemas_default = {
                       }
                     }
                   ]
+                },
+                {
+                  platforms: "android"
+                },
+                {
+                  platforms: [
+                    "windows",
+                    "mac",
+                    "android",
+                    "ios"
+                  ],
+                  browsers: "chrome"
+                },
+                {
+                  platforms: "ios",
+                  browsers: "safari",
+                  device: {
+                    name: "test-iphone",
+                    deviceType: "phone"
+                  }
                 }
               ]
             }
@@ -360500,7 +360660,7 @@ var schemas_default = {
                             ]
                           },
                           browsers: {
-                            description: "Browsers to run tests on.",
+                            description: "Browsers to run tests on. On a mobile (`android`/`ios`) platform entry, the browser runs on the managed device: `chrome` on Android, `safari` on iOS (other combinations skip the context), and it fills in automatically when omitted. Device browsers don't take desktop display config: authored `window`/`viewport` dimensions and `headless: false` are rejected on mobile entries (the device owns its display \u2014 control it via the device descriptor's `headless`/`deviceType`); `headless: true` matches this schema's default and is ignored.",
                             anyOf: [
                               {
                                 type: "string",
@@ -360511,7 +360671,7 @@ var schemas_default = {
                                   "safari",
                                   "webkit"
                                 ],
-                                $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                               },
                               {
                                 type: "object",
@@ -360530,7 +360690,7 @@ var schemas_default = {
                                       "safari",
                                       "webkit"
                                     ],
-                                    $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                    $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                   },
                                   explicit: {
                                     type: "boolean",
@@ -360590,7 +360750,7 @@ var schemas_default = {
                                         "safari",
                                         "webkit"
                                       ],
-                                      $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                      $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                     },
                                     {
                                       type: "object",
@@ -360609,7 +360769,7 @@ var schemas_default = {
                                             "safari",
                                             "webkit"
                                           ],
-                                          $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                          $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                         },
                                         explicit: {
                                           type: "boolean",
@@ -360785,7 +360945,7 @@ var schemas_default = {
                             ]
                           },
                           device: {
-                            description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android`). Same shape as `startSurface.device`.",
+                            description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`). Same shape as `startSurface.device`.",
                             examples: [
                               "pixel7",
                               {
@@ -360824,7 +360984,7 @@ var schemas_default = {
                                     transform: [
                                       "trim"
                                     ],
-                                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                   },
                                   deviceType: {
                                     type: "string",
@@ -360837,11 +360997,11 @@ var schemas_default = {
                                   osVersion: {
                                     type: "string",
                                     minLength: 1,
-                                    description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                    description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                   },
                                   headless: {
                                     type: "boolean",
-                                    description: "Run the Android emulator without a window. Ignored where not applicable."
+                                    description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                   },
                                   orientation: {
                                     type: "string",
@@ -360895,7 +361055,7 @@ var schemas_default = {
                                 "safari",
                                 "webkit"
                               ],
-                              $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                              $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                             },
                             browser: {
                               type: "object",
@@ -360914,7 +361074,7 @@ var schemas_default = {
                                     "safari",
                                     "webkit"
                                   ],
-                                  $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                  $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                                 },
                                 explicit: {
                                   type: "boolean",
@@ -361054,6 +361214,26 @@ var schemas_default = {
                                 }
                               }
                             ]
+                          },
+                          {
+                            platforms: "android"
+                          },
+                          {
+                            platforms: [
+                              "windows",
+                              "mac",
+                              "android",
+                              "ios"
+                            ],
+                            browsers: "chrome"
+                          },
+                          {
+                            platforms: "ios",
+                            browsers: "safari",
+                            device: {
+                              name: "test-iphone",
+                              deviceType: "phone"
+                            }
                           }
                         ]
                       }
@@ -397430,7 +397610,7 @@ var schemas_default = {
                               startSurface: {
                                 $schema: "http://json-schema.org/draft-07/schema#",
                                 title: "startSurface",
-                                description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                                description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                                 components: {
                                   schemas: {
                                     appDescriptor: {
@@ -397482,15 +397662,15 @@ var schemas_default = {
                                         install: {
                                           type: "string",
                                           minLength: 1,
-                                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                         },
                                         activity: {
                                           type: "string",
                                           minLength: 1,
-                                          description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                          description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                         },
                                         device: {
-                                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                           anyOf: [
                                             {
                                               type: "string",
@@ -397523,7 +397703,7 @@ var schemas_default = {
                                                       transform: [
                                                         "trim"
                                                       ],
-                                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                     },
                                                     deviceType: {
                                                       type: "string",
@@ -397536,11 +397716,11 @@ var schemas_default = {
                                                     osVersion: {
                                                       type: "string",
                                                       minLength: 1,
-                                                      description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                      description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                     },
                                                     headless: {
                                                       type: "boolean",
-                                                      description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                      description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                     },
                                                     orientation: {
                                                       type: "string",
@@ -397712,7 +397892,7 @@ var schemas_default = {
                                           transform: [
                                             "trim"
                                           ],
-                                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                         },
                                         deviceType: {
                                           type: "string",
@@ -397725,11 +397905,11 @@ var schemas_default = {
                                         osVersion: {
                                           type: "string",
                                           minLength: 1,
-                                          description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                          description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                         },
                                         headless: {
                                           type: "boolean",
-                                          description: "Run the Android emulator without a window. Ignored where not applicable."
+                                          description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                         },
                                         orientation: {
                                           type: "string",
@@ -397828,15 +398008,15 @@ var schemas_default = {
                                   install: {
                                     type: "string",
                                     minLength: 1,
-                                    description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                    description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                   },
                                   activity: {
                                     type: "string",
                                     minLength: 1,
-                                    description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                    description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                   },
                                   device: {
-                                    description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                    description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                     anyOf: [
                                       {
                                         type: "string",
@@ -397869,7 +398049,7 @@ var schemas_default = {
                                                 transform: [
                                                   "trim"
                                                 ],
-                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                               },
                                               deviceType: {
                                                 type: "string",
@@ -397882,11 +398062,11 @@ var schemas_default = {
                                               osVersion: {
                                                 type: "string",
                                                 minLength: 1,
-                                                description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                               },
                                               headless: {
                                                 type: "boolean",
-                                                description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                               },
                                               orientation: {
                                                 type: "string",
@@ -403215,7 +403395,7 @@ var schemas_default = {
                               "safari",
                               "webkit"
                             ],
-                            $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                            $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                           },
                           explicit: {
                             type: "boolean",
@@ -438920,7 +439100,7 @@ var schemas_default = {
                                     startSurface: {
                                       $schema: "http://json-schema.org/draft-07/schema#",
                                       title: "startSurface",
-                                      description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                                      description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                                       components: {
                                         schemas: {
                                           appDescriptor: {
@@ -438972,15 +439152,15 @@ var schemas_default = {
                                               install: {
                                                 type: "string",
                                                 minLength: 1,
-                                                description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                                description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                               },
                                               activity: {
                                                 type: "string",
                                                 minLength: 1,
-                                                description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                                description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                               },
                                               device: {
-                                                description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                                description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                                 anyOf: [
                                                   {
                                                     type: "string",
@@ -439013,7 +439193,7 @@ var schemas_default = {
                                                             transform: [
                                                               "trim"
                                                             ],
-                                                            description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                            description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                           },
                                                           deviceType: {
                                                             type: "string",
@@ -439026,11 +439206,11 @@ var schemas_default = {
                                                           osVersion: {
                                                             type: "string",
                                                             minLength: 1,
-                                                            description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                            description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                           },
                                                           headless: {
                                                             type: "boolean",
-                                                            description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                            description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                           },
                                                           orientation: {
                                                             type: "string",
@@ -439202,7 +439382,7 @@ var schemas_default = {
                                                 transform: [
                                                   "trim"
                                                 ],
-                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                               },
                                               deviceType: {
                                                 type: "string",
@@ -439215,11 +439395,11 @@ var schemas_default = {
                                               osVersion: {
                                                 type: "string",
                                                 minLength: 1,
-                                                description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                               },
                                               headless: {
                                                 type: "boolean",
-                                                description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                               },
                                               orientation: {
                                                 type: "string",
@@ -439318,15 +439498,15 @@ var schemas_default = {
                                         install: {
                                           type: "string",
                                           minLength: 1,
-                                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                         },
                                         activity: {
                                           type: "string",
                                           minLength: 1,
-                                          description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                          description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                         },
                                         device: {
-                                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                           anyOf: [
                                             {
                                               type: "string",
@@ -439359,7 +439539,7 @@ var schemas_default = {
                                                       transform: [
                                                         "trim"
                                                       ],
-                                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                     },
                                                     deviceType: {
                                                       type: "string",
@@ -439372,11 +439552,11 @@ var schemas_default = {
                                                     osVersion: {
                                                       type: "string",
                                                       minLength: 1,
-                                                      description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                      description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                     },
                                                     headless: {
                                                       type: "boolean",
-                                                      description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                      description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                     },
                                                     orientation: {
                                                       type: "string",
@@ -445216,7 +445396,7 @@ var schemas_default = {
   startSurface_v3: {
     $schema: "http://json-schema.org/draft-07/schema#",
     title: "startSurface",
-    description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+    description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
     components: {
       schemas: {
         appDescriptor: {
@@ -445268,15 +445448,15 @@ var schemas_default = {
             install: {
               type: "string",
               minLength: 1,
-              description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+              description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
             },
             activity: {
               type: "string",
               minLength: 1,
-              description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+              description: "Android main activity override (defaults to the package's launcher activity). Android-only."
             },
             device: {
-              description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+              description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
               anyOf: [
                 {
                   type: "string",
@@ -445309,7 +445489,7 @@ var schemas_default = {
                           transform: [
                             "trim"
                           ],
-                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                         },
                         deviceType: {
                           type: "string",
@@ -445322,11 +445502,11 @@ var schemas_default = {
                         osVersion: {
                           type: "string",
                           minLength: 1,
-                          description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                          description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                         },
                         headless: {
                           type: "boolean",
-                          description: "Run the Android emulator without a window. Ignored where not applicable."
+                          description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                         },
                         orientation: {
                           type: "string",
@@ -445498,7 +445678,7 @@ var schemas_default = {
               transform: [
                 "trim"
               ],
-              description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+              description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
             },
             deviceType: {
               type: "string",
@@ -445511,11 +445691,11 @@ var schemas_default = {
             osVersion: {
               type: "string",
               minLength: 1,
-              description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+              description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
             },
             headless: {
               type: "boolean",
-              description: "Run the Android emulator without a window. Ignored where not applicable."
+              description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
             },
             orientation: {
               type: "string",
@@ -445614,15 +445794,15 @@ var schemas_default = {
       install: {
         type: "string",
         minLength: 1,
-        description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+        description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
       },
       activity: {
         type: "string",
         minLength: 1,
-        description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+        description: "Android main activity override (defaults to the package's launcher activity). Android-only."
       },
       device: {
-        description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+        description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
         anyOf: [
           {
             type: "string",
@@ -445655,7 +445835,7 @@ var schemas_default = {
                     transform: [
                       "trim"
                     ],
-                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                    description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                   },
                   deviceType: {
                     type: "string",
@@ -445668,11 +445848,11 @@ var schemas_default = {
                   osVersion: {
                     type: "string",
                     minLength: 1,
-                    description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                    description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                   },
                   headless: {
                     type: "boolean",
-                    description: "Run the Android emulator without a window. Ignored where not applicable."
+                    description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                   },
                   orientation: {
                     type: "string",
@@ -481296,7 +481476,7 @@ var schemas_default = {
               startSurface: {
                 $schema: "http://json-schema.org/draft-07/schema#",
                 title: "startSurface",
-                description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                 components: {
                   schemas: {
                     appDescriptor: {
@@ -481348,15 +481528,15 @@ var schemas_default = {
                         install: {
                           type: "string",
                           minLength: 1,
-                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                         },
                         activity: {
                           type: "string",
                           minLength: 1,
-                          description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                          description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                         },
                         device: {
-                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                           anyOf: [
                             {
                               type: "string",
@@ -481389,7 +481569,7 @@ var schemas_default = {
                                       transform: [
                                         "trim"
                                       ],
-                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                     },
                                     deviceType: {
                                       type: "string",
@@ -481402,11 +481582,11 @@ var schemas_default = {
                                     osVersion: {
                                       type: "string",
                                       minLength: 1,
-                                      description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                      description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                     },
                                     headless: {
                                       type: "boolean",
-                                      description: "Run the Android emulator without a window. Ignored where not applicable."
+                                      description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                     },
                                     orientation: {
                                       type: "string",
@@ -481578,7 +481758,7 @@ var schemas_default = {
                           transform: [
                             "trim"
                           ],
-                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                         },
                         deviceType: {
                           type: "string",
@@ -481591,11 +481771,11 @@ var schemas_default = {
                         osVersion: {
                           type: "string",
                           minLength: 1,
-                          description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                          description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                         },
                         headless: {
                           type: "boolean",
-                          description: "Run the Android emulator without a window. Ignored where not applicable."
+                          description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                         },
                         orientation: {
                           type: "string",
@@ -481694,15 +481874,15 @@ var schemas_default = {
                   install: {
                     type: "string",
                     minLength: 1,
-                    description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                    description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                   },
                   activity: {
                     type: "string",
                     minLength: 1,
-                    description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                    description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                   },
                   device: {
-                    description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                    description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                     anyOf: [
                       {
                         type: "string",
@@ -481735,7 +481915,7 @@ var schemas_default = {
                                 transform: [
                                   "trim"
                                 ],
-                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                               },
                               deviceType: {
                                 type: "string",
@@ -481748,11 +481928,11 @@ var schemas_default = {
                               osVersion: {
                                 type: "string",
                                 minLength: 1,
-                                description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                               },
                               headless: {
                                 type: "boolean",
-                                description: "Run the Android emulator without a window. Ignored where not applicable."
+                                description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                               },
                               orientation: {
                                 type: "string",
@@ -487805,7 +487985,7 @@ var schemas_default = {
                   ]
                 },
                 browsers: {
-                  description: "Browsers to run tests on.",
+                  description: "Browsers to run tests on. On a mobile (`android`/`ios`) platform entry, the browser runs on the managed device: `chrome` on Android, `safari` on iOS (other combinations skip the context), and it fills in automatically when omitted. Device browsers don't take desktop display config: authored `window`/`viewport` dimensions and `headless: false` are rejected on mobile entries (the device owns its display \u2014 control it via the device descriptor's `headless`/`deviceType`); `headless: true` matches this schema's default and is ignored.",
                   anyOf: [
                     {
                       type: "string",
@@ -487816,7 +487996,7 @@ var schemas_default = {
                         "safari",
                         "webkit"
                       ],
-                      $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                      $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                     },
                     {
                       type: "object",
@@ -487835,7 +488015,7 @@ var schemas_default = {
                             "safari",
                             "webkit"
                           ],
-                          $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                          $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                         },
                         explicit: {
                           type: "boolean",
@@ -487895,7 +488075,7 @@ var schemas_default = {
                               "safari",
                               "webkit"
                             ],
-                            $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                            $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                           },
                           {
                             type: "object",
@@ -487914,7 +488094,7 @@ var schemas_default = {
                                   "safari",
                                   "webkit"
                                 ],
-                                $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                                $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                               },
                               explicit: {
                                 type: "boolean",
@@ -488090,7 +488270,7 @@ var schemas_default = {
                   ]
                 },
                 device: {
-                  description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android`). Same shape as `startSurface.device`.",
+                  description: "Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn't already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`). Same shape as `startSurface.device`.",
                   examples: [
                     "pixel7",
                     {
@@ -488129,7 +488309,7 @@ var schemas_default = {
                           transform: [
                             "trim"
                           ],
-                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                          description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                         },
                         deviceType: {
                           type: "string",
@@ -488142,11 +488322,11 @@ var schemas_default = {
                         osVersion: {
                           type: "string",
                           minLength: 1,
-                          description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                          description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                         },
                         headless: {
                           type: "boolean",
-                          description: "Run the Android emulator without a window. Ignored where not applicable."
+                          description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                         },
                         orientation: {
                           type: "string",
@@ -488200,7 +488380,7 @@ var schemas_default = {
                       "safari",
                       "webkit"
                     ],
-                    $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                    $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                   },
                   browser: {
                     type: "object",
@@ -488219,7 +488399,7 @@ var schemas_default = {
                           "safari",
                           "webkit"
                         ],
-                        $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                        $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                       },
                       explicit: {
                         type: "boolean",
@@ -488359,6 +488539,26 @@ var schemas_default = {
                       }
                     }
                   ]
+                },
+                {
+                  platforms: "android"
+                },
+                {
+                  platforms: [
+                    "windows",
+                    "mac",
+                    "android",
+                    "ios"
+                  ],
+                  browsers: "chrome"
+                },
+                {
+                  platforms: "ios",
+                  browsers: "safari",
+                  device: {
+                    name: "test-iphone",
+                    deviceType: "phone"
+                  }
                 }
               ]
             }
@@ -524735,7 +524935,7 @@ var schemas_default = {
                     startSurface: {
                       $schema: "http://json-schema.org/draft-07/schema#",
                       title: "startSurface",
-                      description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                      description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                       components: {
                         schemas: {
                           appDescriptor: {
@@ -524787,15 +524987,15 @@ var schemas_default = {
                               install: {
                                 type: "string",
                                 minLength: 1,
-                                description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                               },
                               activity: {
                                 type: "string",
                                 minLength: 1,
-                                description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                               },
                               device: {
-                                description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                 anyOf: [
                                   {
                                     type: "string",
@@ -524828,7 +525028,7 @@ var schemas_default = {
                                             transform: [
                                               "trim"
                                             ],
-                                            description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                            description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                           },
                                           deviceType: {
                                             type: "string",
@@ -524841,11 +525041,11 @@ var schemas_default = {
                                           osVersion: {
                                             type: "string",
                                             minLength: 1,
-                                            description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                            description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                           },
                                           headless: {
                                             type: "boolean",
-                                            description: "Run the Android emulator without a window. Ignored where not applicable."
+                                            description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                           },
                                           orientation: {
                                             type: "string",
@@ -525017,7 +525217,7 @@ var schemas_default = {
                                 transform: [
                                   "trim"
                                 ],
-                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                               },
                               deviceType: {
                                 type: "string",
@@ -525030,11 +525230,11 @@ var schemas_default = {
                               osVersion: {
                                 type: "string",
                                 minLength: 1,
-                                description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                               },
                               headless: {
                                 type: "boolean",
-                                description: "Run the Android emulator without a window. Ignored where not applicable."
+                                description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                               },
                               orientation: {
                                 type: "string",
@@ -525133,15 +525333,15 @@ var schemas_default = {
                         install: {
                           type: "string",
                           minLength: 1,
-                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                          description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                         },
                         activity: {
                           type: "string",
                           minLength: 1,
-                          description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                          description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                         },
                         device: {
-                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                          description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                           anyOf: [
                             {
                               type: "string",
@@ -525174,7 +525374,7 @@ var schemas_default = {
                                       transform: [
                                         "trim"
                                       ],
-                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                     },
                                     deviceType: {
                                       type: "string",
@@ -525187,11 +525387,11 @@ var schemas_default = {
                                     osVersion: {
                                       type: "string",
                                       minLength: 1,
-                                      description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                      description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                     },
                                     headless: {
                                       type: "boolean",
-                                      description: "Run the Android emulator without a window. Ignored where not applicable."
+                                      description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                     },
                                     orientation: {
                                       type: "string",
@@ -530520,7 +530720,7 @@ var schemas_default = {
                     "safari",
                     "webkit"
                   ],
-                  $comment: "`safari` is just a shortcut for `webkit`. Included for visibility and to reduce questions."
+                  $comment: "On desktop platforms `safari` is a shortcut for the `webkit` engine. On an `ios` platform entry, `safari` means the real Safari browser on the managed simulator (`webkit` is not supported there). On `android`, `chrome` is the supported browser."
                 },
                 explicit: {
                   type: "boolean",
@@ -566225,7 +566425,7 @@ var schemas_default = {
                           startSurface: {
                             $schema: "http://json-schema.org/draft-07/schema#",
                             title: "startSurface",
-                            description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator via the `device`, `install`, and `activity` fields (iOS lands in A4). Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
+                            description: "Open (provision) a surface and register it by name so later steps can target it with `surface`. Phases A1\u2013A2 ship the desktop native app branch: launch a Windows or macOS application by executable path, `.app` path, bundle ID, or UWP AppUserModelID. macOS additionally requires the Accessibility permission for the process that runs Doc Detective (System Settings \u2192 Privacy & Security \u2192 Accessibility); without it the context lands as SKIPPED with a walkthrough. Phase A3 adds Android apps on a managed emulator, and phase A4 adds iOS app surfaces on macOS via XCUITest/simctl. Browser/process branches and the parallel array form arrive with multi-surface Phase 6. See docs/design/native-app-surfaces.md.",
                             components: {
                               schemas: {
                                 appDescriptor: {
@@ -566277,15 +566477,15 @@ var schemas_default = {
                                     install: {
                                       type: "string",
                                       minLength: 1,
-                                      description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                      description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                                     },
                                     activity: {
                                       type: "string",
                                       minLength: 1,
-                                      description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                      description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                                     },
                                     device: {
-                                      description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                      description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                       anyOf: [
                                         {
                                           type: "string",
@@ -566318,7 +566518,7 @@ var schemas_default = {
                                                   transform: [
                                                     "trim"
                                                   ],
-                                                  description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                                  description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                                 },
                                                 deviceType: {
                                                   type: "string",
@@ -566331,11 +566531,11 @@ var schemas_default = {
                                                 osVersion: {
                                                   type: "string",
                                                   minLength: 1,
-                                                  description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                                  description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                                 },
                                                 headless: {
                                                   type: "boolean",
-                                                  description: "Run the Android emulator without a window. Ignored where not applicable."
+                                                  description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                                 },
                                                 orientation: {
                                                   type: "string",
@@ -566507,7 +566707,7 @@ var schemas_default = {
                                       transform: [
                                         "trim"
                                       ],
-                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                      description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                     },
                                     deviceType: {
                                       type: "string",
@@ -566520,11 +566720,11 @@ var schemas_default = {
                                     osVersion: {
                                       type: "string",
                                       minLength: 1,
-                                      description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                      description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                     },
                                     headless: {
                                       type: "boolean",
-                                      description: "Run the Android emulator without a window. Ignored where not applicable."
+                                      description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                     },
                                     orientation: {
                                       type: "string",
@@ -566623,15 +566823,15 @@ var schemas_default = {
                               install: {
                                 type: "string",
                                 minLength: 1,
-                                description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Lands with the Android phase (A3); on other platforms it is validated but not yet honored."
+                                description: "Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces."
                               },
                               activity: {
                                 type: "string",
                                 minLength: 1,
-                                description: "Android main activity override (defaults to the package's launcher activity). Lands with the Android phase (A3)."
+                                description: "Android main activity override (defaults to the package's launcher activity). Android-only."
                               },
                               device: {
-                                description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Lands with the Android phase (A3).",
+                                description: "Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.",
                                 anyOf: [
                                   {
                                     type: "string",
@@ -566664,7 +566864,7 @@ var schemas_default = {
                                             transform: [
                                               "trim"
                                             ],
-                                            description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain and a matching system image are installed (`doc-detective install android`)."
+                                            description: "Device name and registry identity \u2014 the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`)."
                                           },
                                           deviceType: {
                                             type: "string",
@@ -566677,11 +566877,11 @@ var schemas_default = {
                                           osVersion: {
                                             type: "string",
                                             minLength: 1,
-                                            description: "Platform version used when creating a device; must match an installed system image (install more with `doc-detective install android`). Ignored when `name` already matches an existing device. Default: the newest installed version."
+                                            description: "Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version."
                                           },
                                           headless: {
                                             type: "boolean",
-                                            description: "Run the Android emulator without a window. Ignored where not applicable."
+                                            description: "Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable."
                                           },
                                           orientation: {
                                             type: "string",