@@ -490,6 +490,10 @@ test('usageForCommand resolves ios-system-ui help topic', async () => {
   assert.match(help, /agent-device open com\.apple\.springboard --platform ios/);
   assert.match(help, /longpress <x> <y> on an empty area of the home screen/);
   assert.match(help, /discover them from the current snapshot/);
+  assert.match(
+    help,
+    /verified on iOS simulator; physical-iPhone SpringBoard support is not yet verified/,
+  );
   assert.match(help, /Do not hard-code Edit\/Done\/Add Widget or other SpringBoard label text/);
   assert.match(help, /Reopen the app bundle under test/);
 });
 
@@ -850,7 +850,7 @@ For iOS SpringBoard, widget, or other system-UI surfaces, read agent-device help
 
 Use this when a task needs iOS SpringBoard (home screen), widget add/edit/remove, or other system-UI surfaces instead of the app under test.
 
-This works today by opening SpringBoard as the session app; there is no separate widget/system command. System labels vary by iOS version and locale, so discover them from the current snapshot instead of relying on the literal strings shown below.
+This works today by opening SpringBoard as the session app; there is no separate widget/system command. System labels vary by iOS version and locale, so discover them from the current snapshot instead of relying on the literal strings shown below. This workflow is verified on iOS simulator; physical-iPhone SpringBoard support is not yet verified.
 
 Core loop:
   1. Reach the app state you want to prepare (for example, arrange the widget/Live Activity data the app should show) with normal app automation, then agent-device open com.apple.springboard --platform ios. From an existing app session, agent-device home first also lands on the home screen, but open com.apple.springboard is what actually binds the session to SpringBoard for selector-driven commands.
 
@@ -2624,6 +2624,33 @@ Do not combine final commands with shell operators such as &&, ||, pipes, or sem
     ],
     forbiddenOutputs: [plannedCommand('longpress'), RAW_COORDINATE_TARGET, /--surface menubar/i],
   }),
+  makeCase({
+    id: 'ios-system-ui-springboard-widget-add',
+    contract: [
+      'Platform: iOS',
+      'App name: Agent Device Tester',
+      'Bundle identifier: com.callstack.agentdevicelab',
+      'Session: catalog',
+      'Agent Device Tester is already open on this session; its widget-ready state is prepared',
+      'agent-device open com.apple.springboard --platform ios binds the session to SpringBoard for selector-driven commands; there is no separate widget/system command',
+      'Entering SpringBoard edit mode needs one deliberate empty-space long-press on the home screen; there is no selector for it',
+      'The widget-gallery search-result row for "Calendar" currently returns an unlabeled accessibility node, so select it by coordinates read from a screenshot',
+      'SpringBoard control labels vary by iOS version and locale; discover them from a fresh snapshot -i instead of assuming fixed English strings',
+    ],
+    task: 'Plan the commands to open SpringBoard, enter edit mode, search the widget gallery for "Calendar", add it using the documented coordinate fallback for the unlabeled search-result row, reopen Agent Device Tester to resume app automation, and close the session.',
+    outputs: [
+      plannedCommand('open com.apple.springboard'),
+      /--platform ios/i,
+      /snapshot\b[^\n]*-i\b/i,
+      plannedCommand('longpress'),
+      /(?:^|\n)(?:agent-device\s+)?screenshot\b/i,
+      RAW_COORDINATE_TARGET,
+      /label=["']Add Widget["']/i,
+      plannedCommand('open com.callstack.agentdevicelab'),
+      plannedCommand('close'),
+    ],
+    forbiddenOutputs: [plannedCommandAlternatives(['widget', 'widget add']), /widget\s+add/i],
+  }),
   makeCase({
     id: 'replay-maintenance-update',
     contract: [
 
@@ -1039,7 +1039,7 @@ For CLI-discoverable setup guidance, run `agent-device help physical-device`.
 
 For CLI-discoverable workflow guidance, run `agent-device help ios-system-ui`.
 
-- `agent-device open com.apple.springboard --platform ios` binds the session to SpringBoard on a simulator or physical device today; there is no separate widget/system command.
+- `agent-device open com.apple.springboard --platform ios` binds the session to SpringBoard today; this is verified on iOS simulator only. Physical-iPhone SpringBoard support is not yet verified — see [#1296](https://github.com/callstack/agent-device/issues/1296).
 - The full widget add/edit/remove flow is selector-driven from a fresh `snapshot -i`, except two coordinate-based steps: the empty-space long-press that enters edit mode, and (until fixed) the widget-gallery search-result rows, which currently return unlabeled accessibility nodes.
 - SpringBoard labels vary by iOS version and locale; discover them from the current snapshot rather than hard-coding strings like `Edit` or `Add Widget`.
 - Reopen the app bundle under test to return to normal app automation after a SpringBoard step.