docs: clarify agent-device binary resolution (#511)

Author: thymikee

README.md

@@ -89,7 +89,7 @@ Paste one of these into clients that accept `mcpServers`, such as Cursor project
   "mcpServers": {
     "agent-device": {
       "command": "npx",
-      "args": ["-y", "agent-device@latest", "mcp"]
+      "args": ["-y", "agent-device@<reviewed-version>", "mcp"]
     }
   }
 }
@@ -221,7 +221,6 @@ Used by teams and developers at Callstack, Expensify, Shopify, Kindred, Total Wi
 Agent integration:
 
 - [agent-device skill](skills/agent-device/SKILL.md)
-- [react-devtools skill](skills/react-devtools/SKILL.md)
 - [dogfood skill](skills/dogfood/SKILL.md)
 - MCP router: `agent-device mcp`
 - [agent-device skill on ClawHub](https://clawhub.ai/okwasniewski/agent-device)

skills/agent-device/SKILL.md

@@ -11,7 +11,15 @@ Router only. Private setup before using this skill:
 agent-device --version
 ```
 
-Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, run `npm install -g agent-device@latest`, recheck, then continue. If you cannot upgrade, stop and tell the user. Do not include version/upgrade commands in final plans.
+If that fails but the user installed `agent-device` globally, try the user's login shell before using `npx`:
+
+```bash
+zsh -lic 'command -v agent-device'
+```
+
+If it prints a path, run that absolute path instead of `agent-device`. For non-zsh shells, use the equivalent login-shell command.
+
+Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, stop and tell the user to upgrade the trusted install or approve an exact-version npm command. Do not run `npm install -g agent-device@latest` or `npx -y agent-device@latest` autonomously, and do not include version/upgrade commands in final plans.
 
 Before your first agent-device command or plan, read the version-matched CLI guide:
 

skills/dogfood/SKILL.md

@@ -12,7 +12,9 @@ Router for exploratory QA. Private setup before using this skill:
 agent-device --version
 ```
 
-Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, run `npm install -g agent-device@latest`, recheck, then continue. If you cannot upgrade, stop and tell the user. Do not include version/upgrade commands in final plans.
+If that fails, stop and tell the user to expose a trusted `agent-device` binary on PATH or approve an exact-version npm command. This skill intentionally keeps allowed tools restricted to `agent-device` and `npx agent-device`.
+
+Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, stop and tell the user to upgrade the trusted install or approve an exact-version npm command. Do not run `npm install -g agent-device@latest` or `npx -y agent-device@latest` autonomously, and do not include version/upgrade commands in final plans.
 
 Read current CLI guidance:
 

skills/react-devtools/SKILL.md

@@ -34,7 +34,7 @@ function assertAgentDeviceEvidence(report: SessionReport) {
   const detectedSkills = report.detectedSkills ?? [];
   const hasDetectedSkills = detectedSkills.length > 0;
   const hasBundledDeviceSkill = detectedSkills.some((skill) =>
-    ['agent-device', 'react-devtools', 'dogfood'].includes(skill.skill),
+    ['agent-device', 'dogfood'].includes(skill.skill),
   );
 
   // Some SkillGym runners do not expose skill telemetry. Keep this as a conditional routing

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

@@ -19,14 +19,16 @@ agent-device --version
 agent-device help workflow
 ```
 
-For one-off use without a global install:
+For one-off human use without a global install:
 
 ```bash
-npx -y agent-device@latest --version
-npx -y agent-device@latest help workflow
+npx agent-device --version
+npx agent-device help workflow
 ```
 
-Global install is better for normal agent workflows because repeated commands, skills, and terminal sessions resolve to one stable version.
+Global install is better for normal agent workflows because repeated commands, skills, and terminal sessions resolve to one stable version. Project-local installs are also good when you want a lockfile-pinned agent-device version.
+
+Avoid telling agents to choose an npm version or run `npx -y agent-device@latest` autonomously: it fetches and executes a mutable npm package without a human prompt. For unattended agent use, prefer a trusted installed binary, a project-local install, or a version supplied by the user or project config.
 
 For Node, Xcode, Android SDK, macOS, and iOS device prerequisites, see [Installation](/docs/installation).
 
@@ -47,7 +49,7 @@ Add this as a project rule, custom instruction, or skill equivalent when your ag
 ```text
 Use agent-device only for app/device automation tasks. Before planning commands, run `agent-device --version` and read `agent-device help workflow`. For exploratory QA, read `agent-device help dogfood`. For logs, network, traces, or runtime failures, read `agent-device help debugging`. For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`.
 
-Use the CLI in the integrated terminal. MCP is only a discovery/help router and does not expose device automation tools. Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close`. Use current refs such as `@e3` for exploration and selectors for durable replay. Keep mutating commands against one session serial. Capture screenshots, logs, network, perf, traces, recordings, and `.ad` replay scripts only when they add evidence.
+Use the CLI in the integrated terminal. If `agent-device` is not on PATH but the user installed it globally in another shell, ask the user's login shell for the absolute path and run that path instead. For macOS zsh users, use `zsh -lic 'command -v agent-device'`; for other shells, use the equivalent login-shell lookup. Do not silently fall back to `npx -y agent-device@latest`; ask or use an exact version. MCP is only a discovery/help router and does not expose device automation tools. Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close`. Use current refs such as `@e3` for exploration and selectors for durable replay. Keep mutating commands against one session serial. Capture screenshots, logs, network, perf, traces, recordings, and `.ad` replay scripts only when they add evidence.
 ```
 
 ## MCP router
@@ -67,14 +69,14 @@ Global install configuration:
 }
 ```
 
-No global install variant:
+No global install variant. Pin a user- or project-selected package version for unattended agent use:
 
 ```json
 {
   "mcpServers": {
     "agent-device": {
       "command": "npx",
-      "args": ["-y", "agent-device@latest", "mcp"]
+      "args": ["-y", "agent-device@<reviewed-version>", "mcp"]
     }
   }
 }
@@ -106,6 +108,16 @@ agent-device open <app-or-url> --platform ios
 agent-device snapshot -i
 ```
 
+Some agent clients run commands in an environment that differs from the user's normal install shell. If the user installed `agent-device` globally but the agent cannot find it, have the agent ask the user's login shell for the absolute path.
+
+For macOS zsh users:
+
+```bash
+zsh -lic 'command -v agent-device'
+```
+
+For other shells, use the equivalent login-shell lookup. Then use the printed path for `--version`, `help workflow`, and subsequent commands.
+
 For reviews or planning-only tasks, tell the agent not to run devices unless explicitly requested.
 
 ## Claude Code

website/docs/docs/agent-setup.md

@@ -23,6 +23,16 @@ agent-device help debugging
 agent-device help react-devtools
 ```
 
+Some agent clients run commands in an environment that differs from the user's normal install shell. If `agent-device` is missing in the agent terminal but was installed globally elsewhere, ask the user's login shell for the absolute path.
+
+For macOS zsh users:
+
+```bash
+zsh -lic 'command -v agent-device'
+```
+
+For other shells, use the equivalent login-shell lookup. Then use the printed path for agent commands.
+
 For Cursor, Codex, Claude Code, Windsurf, Cline, Goose, skills, project rules, and MCP configuration, see [AI Agent Setup](/docs/agent-setup). For the first app automation commands, see [Quick Start](/docs/quick-start).
 
 Interactive CLI runs periodically check for a newer published `agent-device` package in the background. When an upgrade is available, the CLI suggests reinstalling the package globally:
@@ -47,12 +57,12 @@ Use [AI Agent Setup](/docs/agent-setup#mcp-router) for copy-paste MCP client con
 ## Without installing
 
 ```bash
-npx -y agent-device@latest --version
-npx -y agent-device@latest help workflow
-npx -y agent-device@latest open Settings --platform ios
+npx agent-device --version
+npx agent-device help workflow
+npx agent-device open Settings --platform ios
 ```
 
-One-off `npx` usage is fine for humans and scripts. For agents, prefer global install so repeated commands and any installed skills resolve to the same CLI version. If an agent cannot rely on skills, it should run `agent-device help` or `agent-device help workflow` before planning device commands.
+One-off `npx` usage is fine for humans and scripts that intentionally fetch from npm. For agents, prefer a global install, a project-local install, or a version supplied by the user or project config so repeated commands resolve to a known CLI. Do not ask agents to choose a version or run `npx -y agent-device@latest` without an explicit trust decision.
 
 ## Requirements