e2e 0.17.0 → 0.18.0

package/docs/migrate/detox.mdx

@@ -1,8 +1,31 @@
 ---
 title: From Detox
 description: Use your existing app build and testIDs with screen, expect, and agent goals.
+icon: "/images/icons/detox.svg"
 ---
 
+import { SetupPrompt } from '../snippets/setup-prompt-card.jsx';
+
+export const migrationPrompt = `Migrate this project's Detox tests to e2e, one spec at a time. Docs: \`https://e2e.tester.army/docs/migrate/detox.md\` and \`https://e2e.tester.army/docs/mobile.md\`
+
+1. Read the migration guide above. It maps \`.detoxrc.js\` and the Detox API to e2e. The mobile guide covers devices and app builds.
+2. If the project has no e2e config (\`e2e.config.ts\` or \`e2e.config.mts\`), run \`npx e2e init --yes\` (or the pnpm or bun equivalent). It writes a web config and an example test, and installs nothing yet. Replace @e2e-dev/web with @e2e-dev/mobile, and rewrite \`tests/example.e2e.ts\` for the mobile engine or delete it.
+3. Read the e2e skill (\`npx e2e guide\` prints it, \`npx e2e guide <topic>\` prints a topic) and follow it for every step below.
+4. If you ran init, ask me which model to use for agent steps: a ChatGPT, GitHub Copilot, OpenCode Console, or SuperGrok subscription, an API key, or a local model. Configure it with its provider package. If it needs a sign-in, give me the \`npx e2e login\` command and wait until I confirm.
+5. Port \`.detoxrc.js\` into the e2e config: one target per platform with \`mobile({ platform })\`, the app's \`bundleId\` and \`appPath\` on the target, and the device type as \`mobile({ device })\`. e2e uses the normal debug or release build, with no Detox framework.
+6. Install dependencies, then run \`npx agent-device doctor\` and fix what it reports.
+7. List the Detox specs and ask me which one to move first. Suggest a flow that needs frequent maintenance.
+8. Rewrite that spec as a \`.e2e.ts\` file under \`tests/\` (e2e runs \`tests/**/*.e2e.ts\` by default), not in the Detox folder. Start it with \`app.open()\`, since nothing launches on its own. \`testID\` props work with \`screen.getByTestId\`. Replace \`waitFor(...).withTimeout()\` with a locator assertion and its \`timeout\`. e2e fails when a query matches several nodes, so narrow those queries.
+9. Keep the launch and the final assertions deterministic, with \`app.open()\` and locator assertions. Where a run of scripted interactions breaks often, propose an \`agent.act\` goal for it instead.
+10. Build and install the app, run the new file with \`npx e2e run <file>\` on each platform target, and fix it until it passes. Keep the Detox spec until I confirm it can go.
+11. Summarize which tests moved, which stayed in Detox, and why.`;
+
+<SetupPrompt>
+
+<Prompt description={migrationPrompt} children={migrationPrompt} actions={["copy", "cursor"]} />
+
+</SetupPrompt>
+
 `@e2e-dev/mobile` drives a simulator or emulator using your normal debug
 or release build. It does not need the Detox framework. React Native
 `testID` props work with `getByTestId` on both platforms.
@@ -131,7 +154,7 @@ to settle, configure the engine's
 [`settle` and `transition` options](/reference/mobile#engine).
 
 <CardGroup cols={2}>
-  <Card title="Testing iOS and Android" icon="mobile-screen" href="/mobile">
+  <Card title="Mobile" icon="mobile-screen" href="/mobile">
     Configure your app and devices.
   </Card>
   <Card title="Mobile engine reference" icon="book" href="/reference/mobile">

package/docs/migrate/maestro.mdx

@@ -1,8 +1,32 @@
 ---
 title: From Maestro
 description: Move Maestro flows to TypeScript with locators, assertions, and agent goals.
+icon: "/images/icons/maestro.svg"
 ---
 
+import { SetupPrompt } from '../snippets/setup-prompt-card.jsx';
+
+export const migrationPrompt = `Migrate this project's Maestro flows to e2e, one flow at a time. Docs: \`https://e2e.tester.army/docs/migrate/maestro.md\` and \`https://e2e.tester.army/docs/mobile.md\`
+
+1. Read the migration guide above. It maps every Maestro config option and command to e2e and marks what e2e does not have yet. The mobile guide covers devices and app builds.
+2. e2e tests are TypeScript. If the project has no \`package.json\`, as in a native iOS or Android project, create the test project in an \`e2e/\` folder beside the app.
+3. If the test project has no e2e config (\`e2e.config.ts\` or \`e2e.config.mts\`), run \`npx e2e init --yes\` (or the pnpm or bun equivalent) there. It writes a web config and an example test, and installs nothing yet. Replace @e2e-dev/web with @e2e-dev/mobile, and rewrite \`tests/example.e2e.ts\` for the mobile engine or delete it.
+4. Read the e2e skill (\`npx e2e guide\` prints it, \`npx e2e guide <topic>\` prints a topic) and follow it for every step below.
+5. If you ran init, ask me which model to use for agent steps: a ChatGPT, GitHub Copilot, OpenCode Console, or SuperGrok subscription, an API key, or a local model. Configure it with its provider package. If it needs a sign-in, give me the \`npx e2e login\` command and wait until I confirm.
+6. Port the flows' \`appId\` and \`.maestro/config.yaml\` into the e2e config: one target per platform with \`mobile({ platform })\`, \`app: { bundleId }\` on each target, and tags as \`{ tags }\` on tests. Move passwords and tokens from \`env\` into \`credentials\` or \`secrets\`.
+7. Install dependencies, then run \`npx agent-device doctor\` and fix what it reports.
+8. List the flows and ask me which one to move first. Suggest one whose \`optional\` steps and \`runFlow: { when }\` branches often need updating.
+9. Rewrite that flow as a \`.e2e.ts\` test under \`tests/\` (e2e runs \`tests/**/*.e2e.ts\` by default), with one awaited call per command. Start it with \`app.open()\`, since nothing launches on its own. Maestro matches text and ids as regular expressions and taps the first of several matches; e2e matches the whole string and fails on several, so use a RegExp, \`.first()\`, or \`.nth()\` where the flow relied on that. \`optional\` and \`runFlow: { when }\` become \`if (await locator.isVisible())\`. Relative selectors such as \`below\` have no port; use a label, a test id, or a goal. Where the guide marks a command missing, use the workaround it gives, or leave that flow in Maestro and tell me why.
+10. Keep the launch and the final assertions deterministic, with \`app.open()\` and locator assertions. Where a run of scripted taps breaks often, propose an \`agent.act\` goal for it instead.
+11. Build and install the app, run the new file with \`npx e2e run <file>\` on each platform target, and fix it until it passes. Keep the Maestro flow until I confirm it can go.
+12. Summarize which flows moved, which stayed in Maestro, and why.`;
+
+<SetupPrompt>
+
+<Prompt description={migrationPrompt} children={migrationPrompt} actions={["copy", "cursor"]} />
+
+</SetupPrompt>
+
 Translate Maestro commands into awaited TypeScript calls. Keep exact
 interactions as locator calls, or give the agent a goal that covers several
 of them. Both runners can use the same simulator or emulator.
@@ -167,7 +191,7 @@ declares `requires: ['device']` so other targets skip it. `Status` is `same`,
 | `optional: true` on a command | the same `isVisible()` check | renamed |
 | `repeat: { times: n }`, `repeat: { while }` | a `for` or `while` loop | renamed |
 | `runScript`, `evalScript`, `${output.x}` | TypeScript in the test | renamed |
-| `http.get`, `http.post`, `json()` | Node `fetch`, see [Testing APIs](/api-testing) | renamed |
+| `http.get`, `http.post`, `json()` | Node `fetch`, see [API](/api-testing) | renamed |
 | `onFlowStart`, `onFlowComplete` | `beforeEach`, `afterEach` | renamed |
 | `startRecording`, `stopRecording` | `test('x', { video: 'on' }, ...)` records that test's whole attempts, on a device the mobile engine records; no start and stop inside a test | renamed |
 
@@ -220,10 +244,10 @@ Start with a flow whose `optional` steps and `runFlow: { when }` branches
 often need updating.
 
 <CardGroup cols={2}>
-  <Card title="Testing iOS and Android" icon="mobile-screen" href="/mobile">
+  <Card title="Mobile" icon="mobile-screen" href="/mobile">
     Configure your app and devices.
   </Card>
-  <Card title="Goals" icon="pen-to-square" href="/goals">
-    Write test steps as goals instead of scripted selectors.
+  <Card title="Core concepts" icon="pen-to-square" href="/core-concepts">
+    Goals, assertions, and locators instead of scripted selectors.
   </Card>
 </CardGroup>

package/docs/migrate/playwright.mdx

@@ -1,8 +1,31 @@
 ---
 title: From Playwright
 description: Run e2e alongside Playwright and migrate tests one file at a time.
+icon: "/images/icons/playwright.svg"
 ---
 
+import { SetupPrompt } from '../snippets/setup-prompt-card.jsx';
+
+export const migrationPrompt = `Migrate this project's Playwright tests to e2e, one spec at a time. Docs: \`https://e2e.tester.army/docs/migrate/playwright.md\`
+
+1. Read the migration guide above. It maps every Playwright config key, API, and CLI flag to e2e and marks what e2e does not have yet.
+2. If the project has no e2e config (\`e2e.config.ts\` or \`e2e.config.mts\`), run \`npx e2e init --yes\` (or the pnpm or bun equivalent). It writes a config and an example test, and installs nothing yet.
+3. Read the e2e skill (\`npx e2e guide\` prints it, \`npx e2e guide <topic>\` prints a topic) and follow it for every step below.
+4. If you ran init, ask me which model to use for agent steps: a ChatGPT, GitHub Copilot, OpenCode Console, or SuperGrok subscription, an API key, or a local model. Configure it with its provider package. If it needs a sign-in, give me the \`npx e2e login\` command and wait until I confirm.
+5. Port \`playwright.config.ts\` into the e2e config with the guide's Config tables. \`baseURL\` and \`webServer\` become the target's \`app\`, \`projects\` become \`targets\`, and browser options under \`use\` (viewport, locale, testIdAttribute) become \`web(...)\` options; \`trace\`, \`video\`, and the timeouts are top-level keys. Keep \`@playwright/test\` installed and the two file patterns apart.
+6. Install dependencies.
+7. List the Playwright specs and ask me which one to move first. Suggest a flow whose steps change often, such as a wizard or a checkout.
+8. Rewrite that spec as a \`.e2e.ts\` file under \`tests/\` (e2e runs \`tests/**/*.e2e.ts\` by default). Map each \`page\` call to \`screen\`, \`app\`, or \`browser\` with the guide. String names in e2e queries match the whole text, case-sensitive, so add \`{ exact: false }\` or a RegExp where the Playwright query matched a fragment. Where the guide marks a feature missing, use the workaround it gives, or leave that test in Playwright and tell me why.
+9. Keep navigation and the final assertions deterministic, with \`app.open()\` and locator assertions. Where a run of scripted interactions breaks often, propose an \`agent.act\` goal for it instead.
+10. Run the new file with \`npx e2e run <file>\` and fix it until it passes. Keep the Playwright spec until I confirm it can go.
+11. Summarize which tests moved, which stayed in Playwright, and why.`;
+
+<SetupPrompt>
+
+<Prompt description={migrationPrompt} children={migrationPrompt} actions={["copy", "cursor"]} />
+
+</SetupPrompt>
+
 `@e2e-dev/web` brings its own pinned `playwright-core`, so your
 `@playwright/test` version is yours to keep. Both runners can stay in one
 project. e2e reads `e2e.config.ts` and finds `tests/**/*.e2e.ts` by default,
@@ -27,7 +50,7 @@ A Playwright key the runner recognizes (`testDir`, `baseURL`, `webServer`,
 | Playwright | e2e | Status |
 | --- | --- | --- |
 | `use.baseURL` | `app: { url }` on the target | renamed |
-| `webServer` | `app: { url, command }` on the target, see [Starting your app](/starting-your-app) | renamed |
+| `webServer` | `app: { url, command }` on the target, see [Starting your app](/web#starting-your-app) | renamed |
 | `webServer` array | `app: { url, command }` on each target; targets declaring the same command share one process. Other dependency processes are not started by this version | missing |
 | `webServer.reuseExistingServer` | `app.command: { reuseExisting: true }`; CI ignores it | renamed |
 | `globalSetup`, `globalTeardown` | not yet; `test.setup` for sign-in, hooks and fixtures for setup code | missing |
@@ -238,7 +261,7 @@ what to do today.
 | `page.exposeFunction()`, `addStyleTag()`, `setExtraHTTPHeaders()`, `emulateMedia()`, `clock` | not yet; `browser.evaluate` appends a `<style>` once the page is open, and returns `null` since its result must be JSON | missing |
 | `context.addCookies()`, `context.cookies()` | `browser.setCookies()`, `browser.cookies()` | web only |
 | `context.clearCookies()` | not yet; `app.clearState()` also clears other persisted state and recreates the context | missing |
-| `request` fixture | Node `fetch`, see [Testing APIs](/api-testing) | by design |
+| `request` fixture | Node `fetch`, see [API](/api-testing) | by design |
 | `context.storageState({ path })` | not yet; sessions are per run and encrypted, see [By design](#by-design) | by design |
 
 ### Test structure
@@ -424,8 +447,8 @@ Start with a flow whose interaction sequence changes often, such as a wizard
 or checkout; stable Playwright tests can stay where they are.
 
 <CardGroup cols={2}>
-  <Card title="Goals" icon="pen-to-square" href="/goals">
-    Write test steps as goals instead of scripted selectors.
+  <Card title="Core concepts" icon="pen-to-square" href="/core-concepts">
+    Goals, assertions, and locators instead of scripted selectors.
   </Card>
   <Card title="Web engine reference" icon="masks-theater" href="/reference/web">
     Every option and every `browser` method.

package/docs/migrate/selenium.mdx

@@ -1,8 +1,32 @@
 ---
 title: From Selenium
 description: Rewrite Selenium flows in TypeScript with locators, retrying assertions, and agent goals.
+icon: "/images/icons/selenium.svg"
 ---
 
+import { SetupPrompt } from '../snippets/setup-prompt-card.jsx';
+
+export const migrationPrompt = `Migrate this project's Selenium tests to e2e, one flow at a time. Docs: \`https://e2e.tester.army/docs/migrate/selenium.md\`
+
+1. Read the migration guide above. It maps Selenium config and WebDriver calls to e2e.
+2. e2e tests are TypeScript. If the Selenium suite is Java, Python, or another language, ask me where the new test project should live, for example an \`e2e/\` folder with its own \`package.json\`.
+3. If that project has no e2e config (\`e2e.config.ts\` or \`e2e.config.mts\`), run \`npx e2e init --yes\` (or the pnpm or bun equivalent) there. It writes a config and an example test, and installs nothing yet.
+4. Read the e2e skill (\`npx e2e guide\` prints it, \`npx e2e guide <topic>\` prints a topic) and follow it for every step below.
+5. If you ran init, ask me which model to use for agent steps: a ChatGPT, GitHub Copilot, OpenCode Console, or SuperGrok subscription, an API key, or a local model. Configure it with its provider package. If it needs a sign-in, give me the \`npx e2e login\` command and wait until I confirm.
+6. Set the target's \`app\` to the URL every \`driver.get\` used, and the command that starts the app if the suite starts it. Move passwords and tokens into \`credentials\` or \`secrets\`.
+7. Install dependencies.
+8. List the page objects and the flows that use them, and ask me which to move first. Suggest one page object and its flows.
+9. Rewrite those flows as \`.e2e.ts\` files under \`tests/\` (e2e runs \`tests/**/*.e2e.ts\` by default). Prefer role, label, and test id queries on \`screen\` over \`By.id\`, CSS, and XPath. Replace explicit waits, implicit waits, and \`Thread.sleep\` with locator assertions, which retry. \`findElement\` takes the first match and e2e fails on several, so narrow those queries. Turn the page object's setup code into a fixture.
+10. Keep navigation and the final assertions deterministic, with \`app.open()\` and locator assertions. Where a run of scripted interactions breaks often, propose an \`agent.act\` goal for it instead.
+11. Run the new files with \`npx e2e run <file>\` and fix them until they pass. Keep the Selenium tests until I confirm they can go.
+12. Summarize which flows moved, which stayed in Selenium, and why.`;
+
+<SetupPrompt>
+
+<Prompt description={migrationPrompt} children={migrationPrompt} actions={["copy", "cursor"]} />
+
+</SetupPrompt>
+
 e2e tests use TypeScript, locators based on roles and labels, and assertions
 that retry until they pass or time out. A Java or Python suite needs to be
 rewritten. Run both suites while you move one flow at a time.
@@ -15,7 +39,7 @@ agent calls; the locator-based example below works without one.
 | Selenium | e2e |
 | --- | --- |
 | The URL in every `driver.get` | `app: { url }` on the target, then relative paths |
-| Starting the app in a script | `app: { url, command }`, see [Starting your app](/starting-your-app) |
+| Starting the app in a script | `app: { url, command }`, see [Starting your app](/web#starting-your-app) |
 | One driver per browser | One target per browser, `web({ browser: 'firefox' })` |
 | Selenium Grid | `workers` for parallelism; `connect` attaches to a remote Chromium over CDP, and a [browser provider](/browser#hosted-browsers) such as [Kernel](/integrations/kernel) leases hosted browsers |
 | `manage().window().setSize` | `web({ viewport })` |
@@ -101,8 +125,8 @@ Start with one page object and the flows that use it; its setup code can
 become a fixture.
 
 <CardGroup cols={2}>
-  <Card title="Goals" icon="pen-to-square" href="/goals">
-    Write test steps as goals instead of scripted selectors.
+  <Card title="Core concepts" icon="pen-to-square" href="/core-concepts">
+    Goals, assertions, and locators instead of scripted selectors.
   </Card>
   <Card title="screen reference" icon="crosshairs" href="/reference/screen">
     Every query, refinement, action, and read.

package/docs/mobile-ci.mdx

@@ -1,6 +1,7 @@
 ---
 title: Mobile CI
 description: Run iOS and Android tests on GitHub Actions, EAS Workflows, Bitrise, and Codemagic.
+icon: "mobile-screen-button"
 ---
 
 A mobile CI job does the same four things on every service: build the app
@@ -16,7 +17,7 @@ credentials, sharding, and exit codes; everything there applies here.
 | Machine | macOS with Xcode and a simulator runtime | Linux with KVM (nested virtualization) |
 | Build | Release simulator `.app`, no signing | Release `.apk` |
 | Device | A booted simulator | A booted emulator |
-| Node | 22.12 or later | 22.12 or later |
+| Node | 24.8 or later, or 22.22.3 or later on 22 | 24.8 or later, or 22.22.3 or later on 22 |
 
 Build Release on both platforms: a React Native or Expo debug build loads
 its JavaScript from Metro, which no CI job here starts, so the app opens on
@@ -115,7 +116,7 @@ simulator; swap in your own build command as long as it writes a simulator
 Release --device generic --no-bundler --output build/ios` builds without
 booting a simulator and writes the `.app` under `build/ios`.
 
-```yaml title=".github/workflows/e2e-mobile.yml"
+```yaml title=".github/workflows/e2e-mobile.yml" expandable
 name: e2e mobile
 
 on:
@@ -247,7 +248,7 @@ The iOS job runs on a macOS runner; the Android one needs a
 `nested-virtualization` Linux runner, the only EAS machines that can run the
 emulator:
 
-```yaml title=".eas/workflows/e2e.yml"
+```yaml title=".eas/workflows/e2e.yml" expandable
 name: e2e
 
 on:
@@ -357,7 +358,7 @@ booting both devices: `xcode-start-simulator` on macOS, and `avd-manager`
 with `wait-for-android-emulator` on Linux. Start the emulator before the
 Gradle build so it boots while the APK compiles.
 
-```yaml title="bitrise.yml"
+```yaml title="bitrise.yml" expandable
 format_version: '25'
 default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git
 
@@ -482,7 +483,7 @@ workflows:
 Android runs on a Linux instance. The Ubuntu image comes with AVDs named `emulator` (API 34),
 `emulator-35`, and `emulator-36`.
 
-```yaml title="codemagic.yaml"
+```yaml title="codemagic.yaml" expandable
 workflows:
   e2e-ios:
     name: e2e iOS

package/docs/mobile.mdx

@@ -1,6 +1,7 @@
 ---
-title: Testing iOS and Android
-description: Set up a simulator or emulator target, write a device test, and know what differs from the web.
+title: Mobile
+description: Set up a simulator, emulator, or connected phone as a target, write a device test, and know what differs from the web.
+icon: "mobile-screen"
 ---
 
 `@e2e-dev/mobile` runs tests on iOS simulators, Android emulators, and
@@ -180,9 +181,79 @@ If none are booted, it boots one. Two workers never drive the same device.
 
 ## Physical devices
 
-A phone connected to your machine works as a device too: name it in
-`device`. Setup and the controls that need a simulator are on
-[Physical devices](/physical-devices).
+agent-device drives a phone plugged into your machine the same way it
+drives a simulator, so a physical device needs no other engine or option.
+List what agent-device sees, then name the phone in `device` as it is
+listed:
+
+<CodeGroup>
+```bash npm
+npx agent-device devices --platform ios
+```
+
+```bash pnpm
+pnpm exec agent-device devices --platform ios
+```
+
+```bash bun
+bunx agent-device devices --platform ios
+```
+</CodeGroup>
+
+```ts
+mobile({ platform: 'ios', device: 'QA iPhone' })
+```
+
+Name a phone by its name, not its id. The engine reads a `device` string as
+an id only when it is a simulator UDID or an `emulator-<port>` serial, so a
+phone's UDID or adb serial is looked up as a name and not found. The first
+device with a matching name wins, so give each phone a unique name: two
+phones both called `iPhone` or `Pixel 8` would bind one phone to two
+workers. Without `device`, a connected phone counts as booted and joins the
+pool beside any booted simulators, so name it to be sure a run lands on it.
+
+Set the phone up once:
+
+- **iOS**: the phone is paired and trusted, unlocked, with Developer Mode
+  on. agent-device builds and signs its XCTest runner onto the phone, so set
+  `AGENT_DEVICE_IOS_TEAM_ID` to your team id and `AGENT_DEVICE_IOS_BUNDLE_ID`
+  to a unique reverse-DNS id (`com.example.agentdevice.runner`); the
+  signing profile must allow that id and `<id>.uitests`. Set them before the
+  first agent-device command, or run `npx agent-device daemon stop` after:
+  a running daemon keeps the environment it started with. The first run
+  builds the runner and takes longer. `app.appPath` must be a signed device
+  build: a simulator `.app` does not install on a phone.
+- **Android**: USB debugging is on and the phone is authorized, listed as
+  `device` in `adb devices`. `app.appPath` is the same `.apk`.
+
+`npx agent-device doctor` checks the setup, and
+`npx agent-device help physical-device` covers iOS signing in detail.
+
+Some device controls need a simulator or emulator, and fail on a phone with
+agent-device's message:
+
+- On an iPhone, every device setting is simulator-only: `app.permissions`
+  and `device.setPermission`, `app.clearState()`, `device.setNetwork`,
+  `device.setAirplaneMode`, `device.setLocation`, `device.clearLocation`,
+  `device.setAppearance`, the biometric methods, and `device.clearKeychain`.
+  So are `device.clipboard`, `device.setClipboard`, and `device.fold`. For a
+  fresh start, reinstall with `device.installApp(path, { reinstall: true })`,
+  with `app.bundleId` on the target or `app` in the options, so agent-device
+  knows which app to remove.
+- An older iPhone that `xcrun devicectl list devices` does not list is
+  driven without CoreDevice: taps, typing, and the screen work, but
+  installs, `--video`, `device.openLink`, and `app.launchArguments` fail.
+  Install the build from Xcode and pin `app.bundleId`.
+- On an Android phone, `device.setLocation` is emulator-only, and
+  `device.setBiometrics('fingerprint', ...)` works only where the phone
+  exposes `cmd fingerprint`.
+- `--video` on an iPhone is built from screenshots at about 15 frames a
+  second, and drops frames.
+- A phone is not this machine, so `localhost` in the app is the phone
+  itself. Point the app at your machine's network address, or on Android
+  forward the port with `adb reverse tcp:<port> tcp:<port>`.
+
+To run on phones in a device farm, see [Hosted devices](#hosted-devices).
 
 ## Hosted devices
 
@@ -270,7 +341,7 @@ record leaves `record` out, and the engine records with agent-device.
 A provider against a typical session API has three requests: create a
 session, poll it until the daemon is reachable, stop it.
 
-```ts title="device-provider.ts"
+```ts title="device-provider.ts" expandable
 import type { DeviceProvider } from '@e2e-dev/mobile';
 
 /**
@@ -350,7 +421,7 @@ A device cloud agent-device speaks to itself needs no session API of your
 own: the provider allocates a lease through a daemon it starts for the run and
 hands the worker the lease scope as `client`.
 
-```ts title="device-cloud-provider.ts"
+```ts title="device-cloud-provider.ts" expandable
 import { createAgentDeviceClient } from 'agent-device';
 import type { DeviceProvider } from '@e2e-dev/mobile';
 
@@ -606,7 +677,7 @@ xcrun simctl shutdown <udid> && xcrun simctl boot <udid>
   <Card title="Mobile engine reference" icon="mobile-screen" href="/reference/mobile">
     Every option, the `device` fixture, and the tool pack.
   </Card>
-  <Card title="Locators" icon="crosshairs" href="/locators">
+  <Card title="Locators" icon="crosshairs" href="/core-concepts#locators">
     Exact taps, swipes, and checks with `screen` and `expect`, on any platform.
   </Card>
 </CardGroup>

package/docs/models.mdx

@@ -1,6 +1,7 @@
 ---
 title: Models
 description: Configure a model with your own subscription, an API key, or a local server.
+icon: "brain"
 ---
 
 import { ModelProvider } from './snippets/model-provider.jsx';
@@ -12,8 +13,9 @@ e2e uses the [AI SDK](https://ai-sdk.dev/providers). You can use
 `e2e init` offers these choices and writes the config for you. For the first
 setup, follow the [quickstart](/quickstart#use-a-subscription-or-api-key).
 
-Tests without agent steps do not need a model. For the built-in agent,
-choose a model that supports tool calls and images. Agent steps need the `ai`
+Tests without agent steps do not need a model. [Decision models](/decision-models), hosted or locally
+hosted, such as Clef or Jev, can drive bounded actions and judge assertions through a custom executor. For the built-in agent,
+choose a model that supports tool calls and images. Steps using the built-in agent need the `ai`
 package installed, whichever provider you use:
 
 <CodeGroup>
@@ -232,6 +234,9 @@ Judgments use the current screen and the question, without the acting
 agent's transcript or summaries. Reports include the model used for each
 judgment. See [Custom executors](/executors) if you replace the built-in agent.
 
+`judge` takes an AI SDK language model. Clef and Jev use a different API;
+use the [decision executor](/decision-models) for `agent.act` and `agent.assert`.
+
 ## Data retention and compliance
 
 Model input is the redacted screen, the step instruction, and the

package/docs/quickstart.mdx

@@ -1,15 +1,17 @@
 ---
 title: Quickstart
 description: Set up e2e with one prompt to your coding agent, or step by step.
+icon: "rocket"
 ---
 
+import { ModelProvider } from './snippets/model-provider.jsx';
 import { SetupPrompt } from './snippets/setup-prompt-card.jsx';
 
 export const setupPrompt = `Set up e2e end-to-end tests in this project. Docs: \`https://e2e.tester.army/docs/quickstart.md\`
 
 1. Run \`npx e2e init --yes\` (or the pnpm or bun equivalent for this project). It writes a web config using Vercel AI Gateway, an example test, the e2e skill, and MCP config. It installs nothing yet.
 2. Read the e2e skill (\`npx e2e guide\` prints it, \`npx e2e guide <topic>\` prints a topic) and follow it for every step below.
-3. Point the target at this app. For a web app, set its URL and the command that starts its dev server. For an iOS or Android app, replace @e2e-dev/web and playwright with @e2e-dev/mobile and rewrite the example test for the mobile engine.
+3. Point the target at this app. For a web app, set its URL and the command that starts its dev server. For an iOS or Android app, replace @e2e-dev/web with @e2e-dev/mobile and rewrite the example test for the mobile engine.
 4. Ask me which model to use for agent steps: a ChatGPT, GitHub Copilot, OpenCode Console, or SuperGrok subscription, an API key, or a local model. Configure it with its provider package. If it needs a sign-in, give me the \`npx e2e login\` command and wait until I confirm.
 5. Install dependencies, run the example test, and fix setup errors until it passes.
 6. Write one test for the most important user flow in this app, run it, and iterate until it passes.`;
@@ -29,7 +31,7 @@ The agent installs the [e2e skill](/coding-agents), so later prompts like
 "add a test for checkout" or "why did this run fail" work without more setup.
 
 <Note>
-Use Node.js 22.12 or newer. On Windows, run inside WSL. Mobile tests also
+Use Node.js 24.8 or newer (22.22.3 or newer on Node.js 22). On Windows, run inside WSL. Mobile tests also
 need Xcode with an iOS simulator runtime, or the Android SDK with an emulator.
 </Note>
 
@@ -63,7 +65,7 @@ need Xcode with an iOS simulator runtime, or the Android SDK with an emulator.
   <Tabs>
     <Tab title="Web">
     Start your app's dev server at `http://localhost:3000`, or set its address
-    in `e2e.config.ts`. You can also [let e2e start it](/starting-your-app).
+    in `e2e.config.ts`. You can also [let e2e start it](/web#starting-your-app).
 
     <Accordion title="Example web config and test">
     This config uses Vercel AI Gateway. The wizard configures the provider you chose.
@@ -122,7 +124,7 @@ test('Settings opens', async ({ app, screen }) => {
 ```
     </Accordion>
 
-    See [Testing iOS and Android](/mobile) to use your own app.
+    See [Mobile](/mobile) to use your own app.
     </Tab>
   </Tabs>
   </Step>
@@ -166,17 +168,26 @@ Connect the provider you chose in the wizard.
   [Subscriptions](/subscriptions) for details.
   </Tab>
   <Tab title="API key">
-  Set your provider's key in the terminal where you run e2e. For Vercel AI
-  Gateway:
+  Select your provider. Install its package and set the variables it reads,
+  if any, in the terminal where you run e2e.
 
-  ```bash
-  export AI_GATEWAY_API_KEY="your-api-key"
-  ```
+  <ModelProvider show="select" />
+
+  <ModelProvider show="install" />
+
+  <ModelProvider show="env" />
+
+  Vercel AI Gateway reads `AI_GATEWAY_API_KEY`, or a
+  [Vercel OIDC token](/models#vercel-oidc-instead-of-a-key) in a project
+  linked with `vercel link`. OpenRouter reads `OPENROUTER_API_KEY`.
+
+  The wizard writes the config for Vercel AI Gateway, OpenRouter, and
+  OpenAI-compatible endpoints. For another provider, replace the model import
+  and `model` value in `e2e.config.ts`, and use `agent` as `agents.default`:
+
+  <ModelProvider show="model" />
 
-  A project linked with `vercel link` can use a
-  [Vercel OIDC token](/models#vercel-oidc-instead-of-a-key) instead.
-  OpenRouter uses `OPENROUTER_API_KEY`. See [Models](/models) for other
-  providers and local models.
+  See [Models](/models) for local models and more options.
   </Tab>
 </Tabs>
 
@@ -246,8 +257,8 @@ to watch a web test, `--no-cache` to skip replaying cached actions.
 ## Next
 
 <CardGroup cols={2}>
-  <Card title="Goals" icon="pen-to-square" href="/goals">
-    Write test steps as goals in natural language.
+  <Card title="Core concepts" icon="pen-to-square" href="/core-concepts">
+    Goals, assertions, and locators.
   </Card>
   <Card title="Signing in" icon="key" href="/authentication">
     Reuse an app login and keep passwords out of model input.

package/docs/reference/agent.mdx

@@ -1,6 +1,7 @@
 ---
 title: agent
 description: Run agent actions, check conditions, and extract structured data.
+icon: "robot"
 ---
 
 Use `act` to interact with the app, `assert` to check the current screen,
@@ -191,7 +192,9 @@ Every `act` observation with unavailable semantics includes that image and
 warning automatically. Earlier node ids are invalid, and the next successful
 semantic capture presents the whole tree again. The screenshot shows the
 current viewport; an unavailable tree does not prove that a control or
-message is absent.
+message is absent. After a secret fill there is no fallback: `act`, and a
+judgment with `vision: true`, fails with `POLICY_DENIED` when semantic
+capture times out before the step does.
 
 If semantic capture fails, trace replay stops and the step cannot record a
 new trace entry, even if the tree later recovers.
@@ -238,7 +241,12 @@ assert(assertion: string, options?: AssertOptions): Promise<void>;
 
 Checks one fresh observation without polling. The judge sees only the
 assertion and current observation, never prior steps or `act` summaries.
-It answers `holds`, `fails`, or `inconclusive`.
+It answers `holds`, `fails`, or `inconclusive`. When what the assertion is
+about appears more than once, such as a total in a summary and on a pay
+button, every instance must agree: one that contradicts it fails. Name
+the place (`the order summary total is $42.00`) to judge only that one. A
+claim about some item, such as `a todo is marked done`, still holds when one
+item matches.
 
 Throws `ASSERTION_FAILED` on a false judgment and `ASSERTION_INCONCLUSIVE`
 when the screen did not show enough to decide. Both carry the explanation
@@ -271,7 +279,9 @@ Observes and judges at once. After a false or inconclusive judgment it
 waits out `interval`, then observes every 500 ms (or every `interval`, when
 shorter) without a model call, and judges again only once the screen
 differs from the one last judged, pixels included under `vision`. Succeeds
-on the first judgment that holds.
+on the first judgment that holds. Judgments follow the `agent.assert`
+rules, so a value shown in more than one place holds only once every
+instance agrees.
 
 Throws `STEP_TIMEOUT` on deadline expiry and `STEP_BUDGET_EXHAUSTED` on
 budget exhaustion, each carrying the last judgment (with the same vision

package/docs/reference/app.mdx

@@ -1,6 +1,7 @@
 ---
 title: app
 description: The portable app lifecycle fixture, available on every platform.
+icon: "cube"
 ---
 
 `app` controls the app's lifecycle and captures screenshots. Each method

package/docs/reference/cli.mdx

@@ -1,6 +1,7 @@
 ---
 title: CLI
 description: Commands, flags, output formats, and exit codes.
+icon: "terminal"
 ---
 
 <CodeGroup>
@@ -56,7 +57,7 @@ bunx e2e --version
 ```
 </CodeGroup>
 
-The CLI needs Node.js 22.12 or newer.
+The CLI needs Node.js 24.8 or newer, or 22.22.3 or newer on Node.js 22. Any package manager installs it (npm, pnpm, Yarn with or without Plug'n'Play, Bun); the CLI itself runs on Node.js, not on the Bun or Deno runtimes (`bunx e2e` runs it on Node.js). Under Yarn Plug'n'Play on Node.js 24.8 through 24.11.0, a `.cts` file fails to load (Node.js rejects the source Yarn's loader hands on); 24.11.1 and later load it.
 
 ## Help and version
 
@@ -140,7 +141,10 @@ bunx e2e init --yes
 ```
 </CodeGroup>
 
-Re-running `init` keeps an existing config and adds no packages for it. Once
+Re-running `init` keeps an existing config and adds no packages for it. MCP
+registration keeps extra settings on the e2e server, such as environment
+variables and client timeouts, even when repairing its launch command. A
+current registration is left byte-for-byte unchanged. Once
 a skill directory exists, later runs refresh copies that differ from the
 installed version and never add a directory the project did not choose. A
 `.claude/skills/e2e/` copy from an earlier version becomes the symlink when
@@ -281,15 +285,15 @@ See [Coding agents](/coding-agents).
 
 <CodeGroup>
 ```bash npm
-npx e2e mcp [--config <path>] [--target <name>] [--headless] [--max-sessions <n>]
+npx e2e mcp [--config <path>] [--target <name>] [--headed] [--max-sessions <n>]
 ```
 
 ```bash pnpm
-pnpm exec e2e mcp [--config <path>] [--target <name>] [--headless] [--max-sessions <n>]
+pnpm exec e2e mcp [--config <path>] [--target <name>] [--headed] [--max-sessions <n>]
 ```
 
 ```bash bun
-bunx e2e mcp [--config <path>] [--target <name>] [--headless] [--max-sessions <n>]
+bunx e2e mcp [--config <path>] [--target <name>] [--headed] [--max-sessions <n>]
 ```
 </CodeGroup>
 
@@ -346,6 +350,8 @@ A positional starting with `-` that names no file is a usage error, exit 2.
 This is what `pnpm test:e2e -- --headed` produces: the `--` reaches e2e and
 `--headed` would otherwise be taken for a file. The message names the direct
 form, `pnpm exec e2e run --headed`.
+For npm, the direct form is `npm exec -- e2e run --headed`; npm needs the
+separator before the binary to pass its flags through.
 
 When nothing is left to run, `NO_TESTS` names the cause: no file matched the
 globs (with look-alike files such as `tests/login.test.ts`), a positional