docs(cli): advertise open --foreground and snapshot --actions in the workflow card

open --foreground (#1670/#1671) and snapshot -i --actions (#1665) shipped
with no mention in the compact `help workflow` card, so a planning model
never discovers either. Add one terse line each: the foreground fast-path
in Bootstrap, and the merged-element custom-action guidance in Validation
and evidence. Stays under the 9,000-byte compact-card budget (8493 -> 8908
bytes).

Adds two help-conformance bench cases per the repo's changed-guidance rule:
foreground-attach-single-sim (correct plan starts with `open --foreground`
in an unambiguous single-sim scenario, fail-closed alternative forbidden)
and merged-card-actions-not-directly-invokable (a merged Bluesky-style feed
card's actions list is evidence, not a selector). Both use a real pinned
sample rebuilt through the production snapshot renderer.

Author: thymikee

scripts/__tests__/help-conformance-sample-producers.ts

@@ -4,6 +4,7 @@ import {
   APP_NOT_INSTALLED_SAMPLE,
   BROWSERSTACK_CONNECT_SAMPLE,
   DEVICE_IN_USE_SAMPLE,
+  MERGED_CARD_ACTIONS_SAMPLE,
   NOT_SETTLED_SAMPLE,
   OFFSCREEN_TARGET_SNAPSHOT_SAMPLE,
   PRIVATE_AX_RECOVERY_SAMPLE,
@@ -267,6 +268,54 @@ export const SAMPLE_PRODUCERS: SampleProducer[] = [
       ).trimEnd();
     },
   },
+  {
+    name: 'MERGED_CARD_ACTIONS_SAMPLE',
+    producer: "the snapshot renderer with --actions naming a merged element's custom actions",
+    sample: MERGED_CARD_ACTIONS_SAMPLE,
+    render: () => {
+      // A Bluesky-style feed item merged into one Link node: its Reply/Repost/
+      // menu controls are AX custom actions, not child nodes, so they only
+      // surface when --actions is passed through to the renderer.
+      const nodes = [
+        {
+          index: 0,
+          ref: 'e1',
+          type: 'Application',
+          label: 'Bluesky',
+          rect: { x: 0, y: 0, width: 390, height: 844 },
+        },
+        {
+          index: 1,
+          ref: 'e2',
+          parentIndex: 0,
+          type: 'Window',
+          rect: { x: 0, y: 0, width: 390, height: 844 },
+        },
+        {
+          index: 2,
+          ref: 'e3',
+          parentIndex: 1,
+          type: 'CollectionView',
+          interactive: true,
+          rect: { x: 0, y: 60, width: 390, height: 700 },
+        },
+        {
+          index: 3,
+          ref: 'e72',
+          parentIndex: 2,
+          type: 'Link',
+          label: 'feedItem-by-whiskers.test',
+          interactive: true,
+          rect: { x: 0, y: 60, width: 390, height: 140 },
+          actions: ['Reply', 'Repost', 'Open post options menu'],
+        },
+      ];
+      return formatSnapshotText(
+        { nodes, backend: 'xctest', truncated: false },
+        { interactiveOnly: true },
+      ).trimEnd();
+    },
+  },
   {
     name: 'DEVICE_IN_USE_SAMPLE',
     producer: 'the real session-open by-session conflict producer',

scripts/help-conformance-cases.mjs

@@ -3,6 +3,7 @@ import {
   APP_NOT_INSTALLED_SAMPLE,
   BROWSERSTACK_CONNECT_SAMPLE,
   DEVICE_IN_USE_SAMPLE,
+  MERGED_CARD_ACTIONS_SAMPLE,
   NOT_SETTLED_SAMPLE,
   OFFSCREEN_TARGET_SNAPSHOT_SAMPLE,
   SETTLE_DIFF_SAMPLE,
@@ -642,4 +643,53 @@ Use the output already shown to determine whether the feed-search UI is present,
       { id: 'noRedundantInstall', pattern: /(?:^|\n)agent-device\s+install\b/i },
     ],
   },
+  {
+    id: 'foreground-attach-single-sim',
+    docs: ['--help:first30', 'workflow'],
+    task: 'You are starting fresh with no active session. The environment guarantees exactly one booted iOS simulator with exactly one app running on it -- the app you want to keep testing. Plan the command to attach to it and get its initial interactive snapshot in a single call (this only resolves unambiguously because of that guarantee, and it rejects an explicit app or device selector), then press the visible Continue control and close the session.',
+    expectations: ['validPlanCommands', 'fullPrefix', 'usesSettleOnMutations', 'opensAndCloses'],
+    matchers: [
+      {
+        id: 'startsWithForegroundOpen',
+        pattern: /^agent-device\s+open\s+--foreground\b/i,
+      },
+      {
+        id: 'pressesContinueAfterAttach',
+        pattern: /agent-device\s+press\s+[^\n]*continue[^\n]*--settle\b/i,
+      },
+    ],
+    forbidden: [
+      {
+        id: 'noAppPositionalWithForeground',
+        pattern: /open[ \t]+(?!--)\S+[^\n]*--foreground\b|open[ \t]+--foreground[ \t]+(?!--)\S+/i,
+      },
+      {
+        id: 'noDeviceSelectorWithForeground',
+        pattern: /--foreground\b[^\n]*--(?:udid|device)\b|--(?:udid|device)\b[^\n]*--foreground\b/i,
+      },
+      { id: 'noRawCoordinateTarget', pattern: RAW_COORDINATE_TARGET },
+    ],
+  },
+  {
+    id: 'merged-card-actions-not-directly-invokable',
+    docs: ['--help:first30', 'workflow'],
+    task: quiz(
+      MERGED_CARD_ACTIONS_SAMPLE,
+      'The goal is to reply to this post. The actions list names "Reply" as a hidden affordance on @e72, but that name is not a pressable selector. What command should run next?',
+    ),
+    expectations: ['validPlanCommands', 'fullPrefix'],
+    matchers: [
+      {
+        id: 'opensCardToReachReply',
+        pattern: /(?:^|\n)agent-device\s+(?:press|click)\s+@e72\b[^\n]*--settle\b/i,
+      },
+    ],
+    forbidden: [
+      {
+        id: 'noPressingActionNameAsSelector',
+        pattern: /(?:^|\n)agent-device\s+(?:press|click|find)\b[^\n]*(?:label|text)="?reply"?/i,
+      },
+      { id: 'noRawCoordinateTarget', pattern: RAW_COORDINATE_TARGET },
+    ],
+  },
 ];

scripts/help-conformance-sample-outputs.mjs

@@ -147,3 +147,19 @@ Next:
 Use the installed package or bundle identifier in open, not the app artifact name.
 After close, run agent-device artifacts --json --session adc-browserstack for provider video and logs.`,
 };
+
+// Merged feed-item card on iOS (#1665): the row itself is the only ref — its
+// Reply/Repost/menu controls have no separate child nodes in the tree, so
+// snapshot -i alone would show a plain link with no way to act on it.
+// snapshot -i --actions names the hidden affordances instead of hiding them
+// silently; the names are evidence only, never directly invokable (help
+// workflow: "reach via its detail screen, labeled children elsewhere, or
+// coordinates").
+export const MERGED_CARD_ACTIONS_SAMPLE = {
+  command: 'agent-device snapshot -i --actions',
+  output: `Snapshot: 4 nodes
+@e1 [application] "Bluesky"
+@e2 [window]
+@e3 [collection]
+@e72 [link] "feedItem-by-whiskers.test" actions: ["Reply", "Repost", "Open post options menu"]`,
+};

src/__tests__/cli-help.test.ts

@@ -135,6 +135,20 @@ test('help workflow documents open/close/relaunch runner guarantees as lifecycle
   assert.match(result.stdout, /Env vars: help physical-device/);
 });
 
+test('help workflow advertises open --foreground and snapshot -i --actions', async () => {
+  const result = await runCliCapture(['help', 'workflow']);
+  assert.equal(result.code, 0);
+  assert.equal(result.calls.length, 0);
+  assert.match(
+    result.stdout,
+    /No session, one booted iOS simulator, one running app: open --foreground attaches and returns the initial snapshot in one call; fails closed \(AMBIGUOUS_MATCH\) otherwise; rejects an explicit app\/--udid\/--device/,
+  );
+  assert.match(
+    result.stdout,
+    /snapshot -i --actions names custom-action affordances hidden inside a merged element \(iOS sim only\); not directly invokable -- reach via its detail screen, labeled children elsewhere, or coordinates/,
+  );
+});
+
 test('help physical-device documents the runner/daemon lifecycle detail moved out of workflow (#1051)', async () => {
   const result = await runCliCapture(['help', 'physical-device']);
   assert.equal(result.code, 0);

src/cli/parser/__tests__/cli-help-topics.test.ts

@@ -253,6 +253,10 @@ test('usageForCommand resolves workflow help topic', async () => {
   );
   assert.match(help, /Known flow: batch \.\/steps\.json \(help scripting\)/);
   assert.match(help, /Shapes and platform quirks: help gestures/);
+  assert.match(
+    help,
+    /No session, one booted iOS simulator, one running app: open --foreground attaches and returns the initial snapshot in one call; fails closed \(AMBIGUOUS_MATCH\) otherwise; rejects an explicit app\/--udid\/--device/,
+  );
   assert.match(help, /Never open artifact paths or invent package ids/);
   assert.match(
     help,
@@ -302,6 +306,10 @@ test('usageForCommand resolves workflow help topic', async () => {
     /confirm the requested end state is actually visible on the current screen, scrolling it into view if needed/,
   );
   assert.match(help, /get text alone, or stopping one screen early, is not enough/);
+  assert.match(
+    help,
+    /snapshot -i --actions names custom-action affordances hidden inside a merged element \(iOS sim only\); not directly invokable -- reach via its detail screen, labeled children elsewhere, or coordinates/,
+  );
   assert.match(help, /Perf\/memory\/log\/network\/trace\/crash: help debugging/);
   assert.match(help, /Recording, save-script, batch, replay repair: help scripting/);
   assert.match(help, /help react-native for Metro\/Re\.Pack reload/);

src/cli/parser/cli-help.ts

@@ -226,6 +226,7 @@ Command shape:
 Bootstrap:
   agent-device devices --platform ios
   agent-device open MyApp --platform ios --device "iPhone 17 Pro"
+  No session, one booted iOS simulator, one running app: open --foreground attaches and returns the initial snapshot in one call; fails closed (AMBIGUOUS_MATCH) otherwise; rejects an explicit app/--udid/--device.
   Install arguments are app/package id then artifact path: agent-device install com.example.app ./dist/app.apk --platform android, then open <id> --relaunch for fresh state. Use reinstall only when explicitly requested.
   Unknown app id: devices, then apps, then open <discovered-app-id>. Never open artifact paths or invent package ids; ask if lookup misses the target.
   Apple CI: prepare ios-runner after boot/install, before replay/test (help prepare). Remote/cloud: connect -> open -> commands -> close -> disconnect (help remote). Reusable scripts, secret-safe fills, replay repair: help scripting.
@@ -264,6 +265,7 @@ Validation and evidence:
   Nearby mutation diff: diff snapshot -i; with no prior snapshot it initializes the baseline (zero changes) instead of failing.
   Named expectations need the exact text/selector via wait/is/get/find -- a bare screenshot/snapshot is not verification. Before declaring a task done, confirm the requested end state is actually visible on the current screen, scrolling it into view if needed; get text alone, or stopping one screen early, is not enough.
   When an action only reveals or reaches a target, verify the exact target named, not just the action. Prefer testIDs/ids/selectors over visible text. Icon/tappable proof: screenshot --overlay-refs; if snapshot is sparse/AX-unavailable, use plain screenshot and coordinates, then retry snapshot -i on another screen.
+  snapshot -i --actions names custom-action affordances hidden inside a merged element (iOS sim only); not directly invokable -- reach via its detail screen, labeled children elsewhere, or coordinates.
   Perf/memory/log/network/trace/crash: help debugging. Recording, save-script, batch, replay repair: help scripting.
 
 React Native: help react-native for Metro/Re.Pack reload, DevTools, RN overlays. JS-only change: metro reload, find "Home"; open --relaunch for native reset.