test: cover restored agent guidance gaps

Author: thymikee

src/utils/__tests__/args.test.ts

@@ -836,6 +836,13 @@ test('usageForCommand resolves workflow help topic', () => {
   assert.match(help, /Do not use CSS selectors/);
   assert.match(help, /Truncated text\/input previews: do not use get text first/);
   assert.match(help, /snapshot -s @e7/);
+  assert.match(help, /Read-only visible\/state question: use snapshot\/get\/is\/find/);
+  assert.match(help, /Use snapshot -i only when refs are needed/);
+  assert.match(help, /install-from-source --github-actions-artifact org\/repo:app-debug/);
+  assert.match(help, /Do not open artifact paths or invent package ids/);
+  assert.match(help, /agent-device get attrs @e4/);
+  assert.match(help, /Ambiguous find: add --first or --last/);
+  assert.match(help, /report that gap instead of typing\/searching\/navigating/);
   assert.match(help, /If snapshot -i shows one, dismiss\/close its visible control/);
   assert.match(help, /agent-device open exp:\/\/127\.0\.0\.1:8081 --platform ios/);
   assert.match(help, /agent-device open "Expo Go" exp:\/\/127\.0\.0\.1:8081 --platform ios/);
@@ -856,6 +863,24 @@ test('workflow help keeps common copyable command forms', () => {
   assert.match(help, /snapshot -s @ref/);
 });
 
+test('usageForCommand resolves remote help topic', () => {
+  const help = usageForCommand('remote');
+  if (help === null) throw new Error('Expected remote help text');
+  assert.match(help, /agent-device open com\.example\.app --remote-config \.\/remote-config\.json/);
+  assert.match(help, /disconnect --remote-config \.\/remote-config\.json/);
+  assert.match(help, /Script flow, per-command config/);
+  assert.match(help, /same --remote-config to every operational command/);
+  assert.match(help, /install-from-source --github-actions-artifact org\/repo:artifact/);
+});
+
+test('usageForCommand resolves macos help topic', () => {
+  const help = usageForCommand('macos');
+  if (help === null) throw new Error('Expected macos help text');
+  assert.match(help, /agent-device click @e66 --button secondary --platform macos/);
+  assert.match(help, /Context menus are not ambient UI/);
+  assert.match(help, /menu-item refs/);
+});
+
 test('usageForCommand resolves dogfood help topic', () => {
   const help = usageForCommand('dogfood');
   if (help === null) throw new Error('Expected dogfood help text');

src/utils/command-schema.ts

@@ -177,6 +177,7 @@ const AGENT_QUICKSTART_LINES = [
   'Default loop: devices/apps -> open -> snapshot -i -> press/fill/get/is/wait/find -> verify -> close.',
   'Use selectors or refs as positional targets: id="submit", label="Allow", or @ref after snapshot -i.',
   'Plain snapshot reads state; snapshot -i is required to refresh interactive refs.',
+  'Read-only visible/state question: use snapshot/get/is/find; use snapshot -i only when refs are needed.',
   'Truncated text/input preview: expand first with snapshot -s @ref, not get text.',
   'RN warning/error overlays can block taps: snapshot -i, dismiss/close, then diff snapshot -i.',
   'Expo Go/dev clients need their provided exp:// or dev-client URL; do not invent app ids.',
@@ -247,7 +248,9 @@ Bootstrap:
   agent-device open <discovered-app-id> --session checkout --platform android
   agent-device install com.example.app ./dist/app.apk --platform android
   agent-device reinstall com.example.app ./build/MyApp.app --platform ios
+  agent-device install-from-source --github-actions-artifact org/repo:app-debug --platform android
   If app id is unknown, plan devices, apps, then open <discovered-app-id>. Install arguments are app/package id then artifact path. Fresh install state: open with --relaunch.
+  Do not open artifact paths or invent package ids. If apps lookup misses the target and no URL/artifact is provided, ask or stop.
 
 Snapshots and refs:
   snapshot reads visible state. snapshot -i gets current interactive refs.
@@ -272,11 +275,15 @@ Text entry:
   Debounced field with no result selector: agent-device wait 1000. Keyboard read-only: keyboard status/get. Blocked control: keyboard dismiss.
 
 Read-only and waits:
+  Read-only visible/state question: use snapshot/get/is/find.
   agent-device snapshot
   agent-device get text 'id="product-title"'
+  agent-device get attrs @e4
   agent-device is visible 'label="Online"'
   agent-device wait visible 'label="Refreshing metrics..."' 3000
   agent-device find "Increment" press --json
+  Use snapshot -i only when refs are needed for an action or targeted query.
+  Ambiguous find: add --first or --last. If info is not visible/exposed, report that gap instead of typing/searching/navigating to reveal it.
 
 Navigation and gestures:
   Use scroll for lists; swipe for coordinate gestures/carousels.
@@ -445,9 +452,16 @@ Normal flow:
   agent-device snapshot
   agent-device disconnect
 
+Script flow, per-command config:
+  agent-device open com.example.app --remote-config ./remote-config.json
+  agent-device snapshot --remote-config ./remote-config.json
+  agent-device disconnect --remote-config ./remote-config.json
+
 Rules:
   connect and disconnect are top-level commands. Do not write agent-device remote connect or agent-device remote disconnect.
   Prefer --remote-config over --daemon-base-url, --tenant, --run-id, and --lease-id in ordinary remote flows.
+  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 remote Android React DevTools, run agent-device react-devtools normally. The CLI opens the needed local service tunnel for the DevTools daemon and cleans it up when the command exits.
   Use --debug when remote connection or transport errors need diagnostic ids and remote log hints.`,
@@ -472,8 +486,13 @@ Menu bar app example:
   agent-device open "Agent Device Tester Menu" --platform macos --surface menubar
   agent-device snapshot -i --platform macos --surface menubar
 
+Context menu example:
+  agent-device click @e66 --button secondary --platform macos
+  agent-device snapshot -i --platform macos
+
 Rules:
   Use open and snapshot -i for menu bar inspection. Do not output inspect as a command.
+  Context menus are not ambient UI: secondary-click a visible target, then re-snapshot and use the new menu-item refs.
   Do not let iOS simulator-set scoping hide macOS desktop targets.
   Prefer refs/selectors over raw coordinates.
   macOS snapshot rects are window-space; use current refs or overlay refs instead of guessing coordinates.`,

test/skillgym/suites/agent-device-smoke-suite.ts

@@ -551,6 +551,48 @@ const SKILL_GUIDANCE_CASES: TestCase[] = [
     ],
     forbiddenOutputs: [/open\s+\.\/dist\/agent-device-tester\.apk/i],
   }),
+  makeCase({
+    id: 'install-from-github-artifact-before-open',
+    contract: [
+      'Platform: Android',
+      'Install source: GitHub Actions artifact callstackincubator/agent-device:agent-device-tester-apk',
+      'Known package after install: com.callstack.agentdevicetester',
+      'Remote daemon can resolve the artifact server-side',
+    ],
+    task: 'Plan commands to install from the GitHub Actions artifact, then open the installed package in fresh runtime state.',
+    outputs: [
+      commandPattern('install-from-source'),
+      /--github-actions-artifact\s+callstackincubator\/agent-device:agent-device-tester-apk/i,
+      commandPattern('open'),
+      /com\.callstack\.agentdevicetester/i,
+      /--relaunch/i,
+    ],
+    forbiddenOutputs: [
+      /curl\b/i,
+      /gh\s+(?:run|artifact|download)/i,
+      /open\s+.*agent-device-tester-apk/i,
+    ],
+  }),
+  makeCase({
+    id: 'hidden-info-do-not-force-ui',
+    contract: [
+      'App name: Agent Device Tester',
+      'Current screen: Home tab',
+      'Question: what is the hidden promo code?',
+      'The current screen does not expose any promo code text or selector',
+      'No interaction was requested',
+    ],
+    task: 'Plan the minimal read-only command to inspect exposed UI without typing, navigating, or mutating the app to reveal hidden information.',
+    outputs: [commandPattern('snapshot')],
+    forbiddenOutputs: [
+      /snapshot -i/i,
+      commandPattern('press'),
+      commandPattern('click'),
+      commandPattern('fill'),
+      commandPattern('type'),
+      commandPattern('open'),
+    ],
+  }),
   makeCase({
     id: 'metro-reload-dev-loop',
     contract: [
@@ -878,6 +920,22 @@ const SKILL_GUIDANCE_CASES: TestCase[] = [
       commandPattern('screenshot'),
     ],
   }),
+  makeCase({
+    id: 'remote-config-script-flow',
+    contract: [
+      'Remote config path: ./remote-config.json',
+      'App package: com.callstack.agentdevicetester',
+      'This is a self-contained script where every command must be explicit',
+      'The remote profile owns tenant, run, lease, and Metro hints',
+    ],
+    task: 'Plan a self-contained remote script that opens the app, captures a snapshot, and disconnects using the remote config on every command.',
+    outputs: [
+      /open\b[^\n]*--remote-config\s+\.\/remote-config\.json/i,
+      /snapshot\b[^\n]*--remote-config\s+\.\/remote-config\.json/i,
+      /disconnect\b[^\n]*--remote-config\s+\.\/remote-config\.json/i,
+    ],
+    forbiddenOutputs: [/--daemon-base-url/i, /--tenant/i, /--run-id/i],
+  }),
   makeCase({
     id: 'macos-menubar-surface',
     contract: [
@@ -890,6 +948,24 @@ const SKILL_GUIDANCE_CASES: TestCase[] = [
     outputs: [/--platform macos/i, /--surface menubar/i, /snapshot\b.*(?:-i\b|\s-i\b)/i],
     forbiddenOutputs: [/--surface app/i, /snapshot --raw/i],
   }),
+  makeCase({
+    id: 'macos-context-menu-secondary-click',
+    contract: [
+      'Platform: macOS',
+      'Current surface: app',
+      'Target row current ref: @e66',
+      'Need to open its native context menu and inspect menu item refs',
+    ],
+    task: 'Plan commands to open the context menu for @e66 and then refresh interactive refs for the menu items.',
+    outputs: [
+      commandPattern('click'),
+      /@e66/i,
+      /--button\s+secondary/i,
+      /--platform\s+macos/i,
+      /snapshot\b.*-i/i,
+    ],
+    forbiddenOutputs: [commandPattern('longpress'), RAW_COORDINATE_TARGET, /--surface menubar/i],
+  }),
   makeCase({
     id: 'replay-maintenance-update',
     contract: [