docs: clarify physical device signing help

src/utils/__tests__/args.test.ts

@@ -972,6 +972,10 @@ test('usage includes agent workflows, config, environment, and examples footers'
     usageText,
     /help react-devtools\s+React Native performance, profiling, component tree, and renders/,
   );
+  assert.match(
+    usageText,
+    /help physical-device\s+Connected phone\/tablet setup and iOS signing prerequisites/,
+  );
   assert.match(
     usageText,
     /help react-native\s+React Native app automation hazards, overlays, Metro, and routing/,
@@ -1122,6 +1126,16 @@ test('usageForCommand resolves remote help topic', () => {
   assert.match(help, /install-from-source --github-actions-artifact org\/repo:artifact/);
 });
 
+test('usageForCommand resolves physical-device help topic', () => {
+  const help = usageForCommand('physical-device');
+  if (help === null) throw new Error('Expected physical-device help text');
+  assert.match(help, /agent-device help physical-device/);
+  assert.match(help, /Start with Automatic Signing and only these env vars/);
+  assert.match(help, /AGENT_DEVICE_IOS_TEAM_ID=ABCDE12345/);
+  assert.match(help, /AGENT_DEVICE_IOS_BUNDLE_ID=com\.yourname\.agentdevice\.runner/);
+  assert.match(help, /profile name\/specifier, not a file path/);
+});
+
 test('usageForCommand resolves macos help topic', () => {
   const help = usageForCommand('macos');
   if (help === null) throw new Error('Expected macos help text');

src/utils/cli-help.ts

@@ -20,6 +20,10 @@ const AGENT_WORKFLOWS = [
     label: 'help react-devtools',
     description: 'React Native performance, profiling, component tree, and renders',
   },
+  {
+    label: 'help physical-device',
+    description: 'Connected phone/tablet setup and iOS signing prerequisites',
+  },
   {
     label: 'help remote',
     description: 'Remote/cloud config, tenants, leases, and local service tunnels',
@@ -406,6 +410,36 @@ Slow-flow investigation:
   For 15-20s async work, use wait with the exact expected text or selector instead of repeated snapshots.
   Report React render offenders separately from network/backend waits and device frame/CPU/memory findings.`,
   },
+  'physical-device': {
+    summary: 'Connected phone/tablet setup and iOS signing prerequisites',
+    body: `agent-device help physical-device
+
+Use this when the target is connected hardware instead of a simulator/emulator.
+For simulator/emulator workflows, use help workflow.
+
+Discovery:
+  agent-device devices --platform ios
+  agent-device devices --platform android
+  Use --device <name-or-udid> only when multiple devices are present.
+
+iOS physical-device prerequisites:
+  Xcode and xcrun devicectl must be available from the selected Xcode.
+  The device must be paired/trusted, connected, unlocked when needed, and have Developer Mode enabled.
+  The AgentDeviceRunner XCTest host must be signed before commands can run on a physical device.
+  Start with Automatic Signing and only these env vars:
+    AGENT_DEVICE_IOS_TEAM_ID=ABCDE12345
+    AGENT_DEVICE_IOS_BUNDLE_ID=com.yourname.agentdevice.runner
+  Find team ids and Apple Development signing certificates with:
+    security find-identity -v -p codesigning
+  If Xcode cannot choose a profile, set AGENT_DEVICE_IOS_PROVISIONING_PROFILE to the profile name/specifier, not a file path.
+  AGENT_DEVICE_IOS_SIGNING_IDENTITY is optional; omit it unless xcodebuild asks for a specific identity.
+  The profile/team must allow AGENT_DEVICE_IOS_BUNDLE_ID and <id>.uitests.
+  First-run XCTest setup/build can take longer than normal commands; keep the device connected and use --debug to inspect signing/build diagnostics if setup times out.
+
+Android physical-device prerequisites:
+  Enable USB debugging and confirm the device appears in agent-device devices --platform android.
+  Android does not need the iOS runner signing setup. For React Native/Expo Metro reachability, read help react-native.`,
+  },
   remote: {
     summary: 'Remote config, tenant, lease, and remote host flow',
     body: `agent-device help remote
@@ -436,6 +470,7 @@ Rules:
   For self-contained scripts, pass the same --remote-config to every operational command, including disconnect; a preceding connect is optional but not required.
   For remote artifact installs, use install-from-source <url> or install-from-source --github-actions-artifact org/repo:artifact; do not download CI artifacts locally first.
   After connect, let the active remote connection supply runtime hints.
+  For connected phone/tablet setup and iOS signing prerequisites, read agent-device help physical-device.
   For remote Android and iOS bridge React DevTools, run agent-device react-devtools normally. The CLI opens the needed local service tunnel for the DevTools daemon and keeps it alive until agent-device react-devtools stop or disconnect.
   Use --debug when remote connection or transport errors need diagnostic ids and remote log hints.`,
   },

website/docs/docs/commands.md

@@ -811,17 +811,21 @@ agent-device session list --json
 - `session list` shows active daemon sessions and their tracked device/app context.
 - Use `--json` when you want to inspect or script against the raw session metadata.
 
-## iOS device prerequisites
+## iOS physical-device prerequisites
+
+For CLI-discoverable setup guidance, run `agent-device help physical-device`.
 
 - Xcode + `xcrun devicectl` available.
-- Paired physical device with Developer Mode enabled.
-- Use Automatic Signing in Xcode, or pass optional env overrides:
+- Paired/trusted physical device, connected, unlocked when needed, with Developer Mode enabled.
+- The `AgentDeviceRunner` XCTest host must be signed before commands can run on a physical device.
+- Start with Automatic Signing and only these env vars:
   - `AGENT_DEVICE_IOS_TEAM_ID`
-  - `AGENT_DEVICE_IOS_SIGNING_IDENTITY` (optional)
-  - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
   - `AGENT_DEVICE_IOS_BUNDLE_ID` (runner bundle-id base; tests use `<id>.uitests`)
-- Free Apple Developer (Personal Team) accounts can fail on unavailable generic bundle IDs; set `AGENT_DEVICE_IOS_BUNDLE_ID` to a unique reverse-DNS value.
-- First-run XCTest setup/build can take longer than normal commands; keep the device connected and inspect daemon diagnostics if setup times out.
+- Find team ids and Apple Development signing certificates with `security find-identity -v -p codesigning`.
+- If Xcode cannot choose a profile, set `AGENT_DEVICE_IOS_PROVISIONING_PROFILE` to the profile name/specifier, not a file path.
+- `AGENT_DEVICE_IOS_SIGNING_IDENTITY` is optional; omit it unless `xcodebuild` asks for a specific identity.
+- The profile/team must allow `AGENT_DEVICE_IOS_BUNDLE_ID` and `<id>.uitests`.
+- First-run XCTest setup/build can take longer than normal commands; keep the device connected and use `--debug` to inspect signing/build diagnostics if setup times out.
 - If you override the iOS runner derived-data path and also force cleanup, keep `AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH` under the project `.tmp/` directory. Other cleanup override paths are rejected with a recovery hint.
 - For daemon startup troubleshooting:
   - follow stale metadata hints for `<state-dir>/daemon.json` and `<state-dir>/daemon.lock` (`state-dir` defaults to `~/.agent-device`)