e2e 0.16.0 → 0.18.0

package/docs/debugging.mdx

@@ -1,6 +1,7 @@
 ---
 title: Debugging a run
 description: Read the report, open the evidence, watch the browser, and see what the model was sent.
+icon: "magnifying-glass"
 ---
 
 Start with the failure in the terminal. Every run also writes
@@ -63,7 +64,9 @@ URL: `http://127.0.0.1:3000/todos`
 
 `Look at` points to the failing call. Assertion failures include expected
 and observed values; locator failures include the requested locator and
-nearby matches. Repeated failure details help you compare attempts.
+nearby matches. Repeated failure details help you compare attempts. The
+runner spends at most 5 s capturing the screen and screenshot once per failed
+attempt; an app that does not answer in time gets no screen section.
 
 ## The report
 
@@ -91,7 +94,9 @@ failed result:
 
 Artifacts land under `.e2e/artifacts/` (`<output>/artifacts/` when the
 [`output`](/reference/config#output) is moved), one directory per attempt.
-Each run empties it first, so it holds the latest run's evidence:
+Each run empties it first, so it holds the latest run's evidence. A
+`--last-failed` rerun instead empties it down to the files the report it
+reruns names, and writes its own under `rerun-<n>/`:
 
 - **Screenshots.** Failed attempts capture one whenever the engine can and
   pixels are allowed. The built-in `agent.assert` also captures one after
@@ -99,12 +104,13 @@ Each run empties it first, so it holds the latest run's evidence:
   be withheld. Use `app.screenshot('label')` to capture one explicitly.
 - **Playwright traces** on the attempts the [`trace`](/reference/config#trace)
   mode records: every attempt locally, the first retry in CI. Open one with
-  `npx playwright show-trace <file>`; `--trace off` skips the cost for one
-  run, `--trace` records every attempt of a CI run.
+  `npx playwright-core@1.63.0 show-trace <file>` (`pnpm dlx` under pnpm);
+  `--trace off` skips the cost for one run, `--trace` records every attempt
+  of a CI run.
 - **Downloads** saved through `browser.waitForDownload`, recorded with kind
-  `download`. They are the app's bytes: `redaction: "incomplete"` unless a
-  secret reached the session (filled, or held by the engine for basic auth)
-  and the file is text, which the runner rewrites and marks `complete`.
+  `download`. They are the app's bytes: `redaction: "incomplete"` unless the
+  session knows a secret value and the file is text, which the runner rewrites and
+  marks `complete`.
 - **Videos** and **agent transcripts** when you ask for them; see below.
 
 After a secret fill, no screenshots are taken for the rest of the attempt; see
@@ -193,9 +199,16 @@ stdout | web tests/todos.e2e.ts > adds a todo
 hello from the test
 ```
 
-Nothing is buffered or dropped: every line appears when it is written, in a
-pipe or a CI log as much as in a terminal. The output is not part of the
-report; use `expect` or an artifact for anything a later reader needs.
+Output from outside a test, such as a test file's top level or a reporter,
+prints under `stdout | runner` or `stderr | runner`. Both streams print on
+stdout, in a pipe or a CI log too. Without the `list` reporter, output
+goes to its own stream as written.
+
+Secret values are [redacted](/security#redaction). Output printed while the
+config loads appears once it has loaded, before the run header, and is
+dropped for a warning if the load fails. Every other line appears when it
+is written. The output is not part of the report; use `expect` or an
+artifact for anything a later reader needs.
 
 ## Agent steps
 
@@ -261,13 +274,13 @@ large raw JSON file.
 
 Replayed steps make no model call and leave no AI trace. Add `--no-cache`
 when you need to inspect the whole flow or rule out a stale recording. See
-[Caching agent steps](/cache).
+[Caching](/cache).
 
 ## Common errors
 
 | Code | Usual cause | Fix |
 | --- | --- | --- |
-| `APP_UNREACHABLE` | Nothing answers at `app.url`, or `app.command` never became ready; on a device, the message may name the iOS automation runner instead (busy, wedged, or a snapshot it could not present) | Set `app.command.log` and read it; check the port; raise `app.command.startupTimeout`. For the runner, follow the recovery in the message: `npx agent-device daemon stop`, reboot the simulator (see [Testing iOS and Android](/mobile#troubleshooting)) |
+| `APP_UNREACHABLE` | Nothing answers at `app.url`, or `app.command` never became ready; on a device, the message may name the iOS automation runner instead (busy, wedged, or a snapshot it could not present) | Set `app.command.log` and read it; check the port; raise `app.command.startupTimeout`. For the runner, follow the recovery in the message: `npx agent-device daemon stop`, reboot the simulator (see [Mobile](/mobile#troubleshooting)) |
 | `APP_ALREADY_RUNNING` | Something already serves `app.url` when the runner wanted to start `app.command` | Stop it, or set `reuseExisting: true` for local runs |
 | `LOCATOR_NOT_FOUND` | Wrong role or name, text not exact, element inside an iframe, page not open | Read the markup for the accessible name; try `exact: false`; `browser.frameLocator` for iframes; `--headed` to look |
 | `LOCATOR_AMBIGUOUS` | Two matches: a hidden duplicate, a repeated label | Add `{ name }`, scope under a container, `filter`, `first()`, or `{ visible: true }` |

package/docs/decision-models.mdx

@@ -0,0 +1,142 @@
+---
+title: Decision models
+description: Run bounded actions with a decision model and a small text model instead of a full LLM agent.
+icon: "scale-balanced"
+---
+
+`@e2e-dev/decision` runs `agent.act` and `agent.assert` through a decision
+model instead of an LLM. For each action the decision model answers one
+request: which operation, and which element for each operation that has
+more than one, chosen from what the executor builds out of the latest
+semantic tree. It never generates free text: when the choice is `type`, a
+small language model writes the field value. Both models are
+plain AI SDK models, so any decision model provider that answers `choice`
+questions with probability distributions (Jev) and any language-model
+provider works; the runner still authorizes every dispatched action.
+
+## Install and configure
+
+<CodeGroup>
+```bash npm
+npm install -D @e2e-dev/decision
+```
+
+```bash pnpm
+pnpm add -D @e2e-dev/decision
+```
+
+```bash bun
+bun add -d @e2e-dev/decision
+```
+</CodeGroup>
+
+The decision model answers `choice` questions with probability
+distributions; the text model writes field values. Each installs as its
+own package. Decision models need `ai` 7, version 7.0.128 or later:
+
+<CodeGroup>
+```bash npm
+npm install -D @ai-sdk/typesafe-ai @openrouter/ai-sdk-provider
+```
+
+```bash pnpm
+pnpm add -D @ai-sdk/typesafe-ai @openrouter/ai-sdk-provider
+```
+
+```bash bun
+bun add -d @ai-sdk/typesafe-ai @openrouter/ai-sdk-provider
+```
+</CodeGroup>
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { web } from '@e2e-dev/web';
+import { decisionExecutor } from '@e2e-dev/decision';
+import { typeSafeAi } from '@ai-sdk/typesafe-ai';
+import { openrouter } from '@openrouter/ai-sdk-provider';
+
+export default {
+  targets: [{ engine: web(), app: { url: 'http://localhost:3000' } }],
+  agents: {
+    default: {
+      executor: decisionExecutor({
+        model: typeSafeAi.decisionModel('jev-latest'),
+        textModel: openrouter('inception/mercury-2.5'),
+      }),
+    },
+  },
+} satisfies E2EConfig;
+```
+
+`evaluationModel()` instances still work. A model id string or a language
+model in `model` fails config load with `INVALID_CONFIG`.
+
+Tests stay plain natural language, with no params needed:
+
+```ts title="tests/todos.e2e.ts"
+import { test, expect } from 'e2e';
+
+test('adds a todo', async ({ app, screen, agent }) => {
+  await app.open('/todos');
+  await agent.act('Add a todo named Buy coffee, and verify it is listed.');
+  await expect(screen.getByTestId('todo')).toContainText('Buy coffee');
+  await agent.assert('The todo list contains Buy coffee.');
+});
+```
+
+## How text gets typed
+
+The decision model only ever names an element index. When it picks `type`,
+the text model writes the value from the goal, the field's label, and the
+page text, and the executor types exactly that string. Model output never
+becomes a selector, a URL, or a key. When the goal supplies no value,
+nothing is typed and the decision model picks another action. Password
+fields never reach the text model; secrets stay declared handles that only
+`typeSecret` fills.
+
+The text model is also the agent's judgment tier: it is exposed as the
+executor's `model`, so `waitFor` and `extract` use it too. It can come
+from the agents entry's `model` instead. Without either, `type` is never
+offered.
+
+## Finishing a step
+
+When the decision model answers `done` or `failed`, the executor checks
+the claim on a fresh screen with one question: is the step's task complete?
+It sees the step's non-secret params, the actions taken with the non-secret
+values typed, and the page, including the text of named status regions, but
+no model reasoning or secret. A confirmed `done` passes the
+step and a confirmed `failed` fails it with `ACTION_FAILED`. An
+unconfirmed claim goes back to the decision model as history; the second one
+ends the step, as `ACTION_FAILED` when the screen contradicts the goal and
+as `blocked` (`AUTOMATION_UNSUPPORTED`) otherwise.
+
+## Gates
+
+Both gates are off by default: the executor follows the most probable
+choice. Set `minProbability` or `minConfidence` to block weaker actions,
+reject weaker completion checks, and fail weaker assertions as
+inconclusive instead:
+
+```ts title="Executor setup"
+const executor = decisionExecutor({ model, minProbability: 0.9, minConfidence: 0.8 });
+```
+
+Probability and confidence are different provider fields: probability is the
+selected option's share of the answer distribution, confidence is the
+provider's separate statistic. A threshold is a policy choice; measure
+accuracy on your own tests before changing it.
+
+## Limits
+
+- No vision: screenshots never reach the model; canvas-only controls and
+  image-based targets are not implemented.
+- No `navigate`: in-app navigation is a `tap` on a link. URLs belong in
+  test code (`browser.goto`, `app.open`).
+- No multi-select `listbox` in v1.
+- The choice cap is 255 options per question (TypeSafe's limit). Larger
+  screens list viewport nodes first and count the rest as omitted, so the
+  model can scroll; the step never blocks just for being large.
+- Drag, upload, and hover are not offered in v1.
+- `waitFor` and `extract` use the text model through the runner's
+  built-in judgment tier.

package/docs/example-projects.mdx

@@ -0,0 +1,32 @@
+---
+title: Example projects
+description: Run standalone e2e examples with Vite, Next.js, Expo, and SwiftUI.
+icon: "folder-open"
+---
+
+Each example is a standalone greeting app with three locator tests and two
+agent tests. Enter a name, press Greet, and check the result. The projects
+install published e2e packages from npm and work outside this repository.
+
+<CardGroup cols={2}>
+  <Card title="Vite" icon="/images/examples/vite.svg" href="https://github.com/tester-army/e2e/tree/main/examples/with-vite" cta="View example" arrow>
+    React with Vite. Run locator and agent tests in Chromium.
+  </Card>
+  <Card title="Next.js" icon="/images/examples/nextjs.svg" href="https://github.com/tester-army/e2e/tree/main/examples/with-next" cta="View example" arrow>
+    Next.js App Router. The runner starts the app and tests it in Chromium.
+  </Card>
+  <Card title="Expo" icon="/images/integrations/expo.svg" href="https://github.com/tester-army/e2e/tree/main/examples/with-expo" cta="View example" arrow>
+    React Native with Expo. Run the same tests on web, an iOS simulator, or an Android emulator.
+  </Card>
+  <Card title="SwiftUI" icon="/images/examples/swiftui.png" href="https://github.com/tester-army/e2e/tree/main/examples/with-swiftui" cta="View example" arrow>
+    A native iOS app with an Xcode project. Run tests on an iPhone simulator.
+  </Card>
+</CardGroup>
+
+Follow each project's README for installation, builds, and run commands.
+The config and tests live beside the app. The SwiftUI project keeps them
+in its `e2e/` folder.
+
+Locator tests need no model. Set `AI_GATEWAY_API_KEY` to run the agent
+tests; without it, those tests skip. See [Models](/models) for model setup
+and the [Quickstart](/quickstart) to add e2e to your own app.

package/docs/executors.mdx

@@ -1,6 +1,7 @@
 ---
 title: Custom executors
 description: Customize the agent loop or implement your own step executor.
+icon: "microchip"
 ---
 
 Use a custom executor when a `system` prompt and [project tools](/tools) are
@@ -14,6 +15,8 @@ not enough. There are two options:
    `ai` package installed.
 
 Both receive a deadline, redacted observations, and checked action methods.
+For a provider that returns bounded choices instead of generated text, see
+the [Clef and Jev decision executor](/decision-models).
 The runner records their verdicts. Either goes under `executor` in an agents
 entry, beside the options that still apply: `model`, `judge`, `context`, and
 the budgets. An entry with `executor` rejects `system` and `tools`; pass
@@ -215,8 +218,10 @@ default, follows the configured cache mode. A recorded step replays without
 calling `runStep`. A replay that stops partway calls `runStep` with
 `ctx.replayedPrefix`: continue from the current screen and do not redo the
 replayed actions. What a step does through `ctx.actions` is recorded; a
-mutating tool call leaves a gap the executor fills on replay. Entries are not
-keyed by executor, so an entry one agent recorded replays for another.
+mutating tool call leaves a gap the executor fills on replay. Entries are
+keyed by the configured agent and its context, so an entry one agent
+recorded never replays for another; the executor itself is not part of the
+key, so changing an agent's executor keeps its entries.
 
 `'off'` never replays or records the executor's steps, so every step reaches
 `runStep`. Use it for a brain whose own history or memory is the source of

package/docs/explore.mdx

@@ -1,6 +1,7 @@
 ---
 title: Exploring without a test
 description: Give the agent a goal instead of a test file. It plans its own steps, drives the app, and reports what it finds.
+icon: "compass"
 ---
 
 Use `e2e explore` to investigate a flow without writing a test. Give the

package/docs/github.mdx

@@ -1,6 +1,7 @@
 ---
 title: Pull request comments
 description: The @e2e-dev/github reporter posts one comment per run from GitHub Actions and keeps it current.
+icon: "code-pull-request"
 ---
 
 `@e2e-dev/github` posts test results as a pull request comment, including
@@ -63,14 +64,17 @@ Upload artifacts even when a retry passes. Each failure's evidence links open
 the run's Artifacts section; inside the download, every test has a directory
 named after it and the agent that ran it
 (`web/tests_billing.e2e.ts__upgrades/default/attempt-0/`), so keep
-`path: .e2e/artifacts` and the download lines up with the report. A project
+`path: .e2e/artifacts` and the download lines up with the report. A
+`--last-failed` rerun keeps the first run's directories and puts its own
+under `rerun-1/`, so a flaky test's failed attempt still links to its own
+files. A project
 below the checkout root, such as `packages/e2e-tests`, gets source links under
 that path. The checkout root is the nearest directory holding `.git` inside
 `GITHUB_WORKSPACE`, so `actions/checkout` with a `path` input works too.
 
 ## The comment
 
-```markdown
+```markdown expandable
 ### 🔴 e2e: 1 failed, 1 flaky, 3 passed, 1 skipped
 9 agent steps · 4 replayed from cache · 31 model calls · 128k tokens (62% cached) · $0.31
 
@@ -143,9 +147,14 @@ passes:
 
 The comment covers the whole suite, not only the tests the rerun ran again.
 A test that failed and then passed shows as flaky, a test that failed twice
-stays failed, and the rest keep their first-pass results. The comment
-matches the job's status: it stays red when another filter kept a failed
-test out of the rerun.
+stays failed, one that was interrupted and then passed shows as passed, and
+the rest keep their first-pass results. The comment stays red while the
+rerun left out something it owed: a failed test, one `--max-failures` stopped
+before it ran, or a failed `beforeAll` or `afterAll` whose tests another
+filter kept out of the rerun. It shows ⏹️ when the rerun left out a test the
+first pass never finished. The rerun's own exit code counts only what it ran.
+A failed attempt's evidence links to the first run's files, which the rerun
+keeps.
 
 ## Matrix jobs
 

package/docs/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: Introduction
 description: Open source AI testing for web and mobile apps. Spend less time on tests and more time building.
+icon: "house"
 ---
 
 import { VideoCard } from './snippets/video-card.jsx';
@@ -9,9 +10,9 @@ e2e is a next-generation testing framework for web and mobile
 apps, built to keep up with the speed we ship software today.
 
 You choose how agentic each test is: fully deterministic with
-[locators](/writing-tests#deterministic-apis-screen-and-expect) and
+[locators](/core-concepts#locators) and
 [assertions](/reference/expect#locator-matchers), fully driven by an agent
-from [goals](/writing-tests#goals-agent-act) in natural language, or a mix of
+from [goals](/core-concepts#goals) in natural language, or a mix of
 both in the same test.
 
 <VideoCard
@@ -49,7 +50,7 @@ you shipped.
 ## How it works
 
 - **Targets.** Each test runs once per target, such as Chromium or an iPhone
-  simulator. The [web engine](/starting-your-app) drives browsers through
+  simulator. The [web engine](/web) drives browsers through
   Playwright, the [mobile engine](/mobile) drives iOS simulators and Android
   emulators through agent-device, and you can
   [write your own](/writing-an-engine).
@@ -70,8 +71,11 @@ you shipped.
   <Card title="Quickstart" icon="rocket" href="/quickstart">
     One prompt for your coding agent, or set up by hand.
   </Card>
-  <Card title="Writing tests" icon="pen-to-square" href="/writing-tests">
-    Write goals, check outcomes, and extract data.
+  <Card title="Example projects" icon="folder-open" href="/example-projects">
+    Run a standalone app with Vite, Next.js, Expo, or SwiftUI.
+  </Card>
+  <Card title="Core concepts" icon="pen-to-square" href="/core-concepts">
+    Goals, assertions, and locators.
   </Card>
   <Card title="Coding agents" icon="robot" href="/coding-agents">
     Let your coding agent write, run, and debug tests.

package/docs/integrations/eas.mdx

@@ -2,6 +2,7 @@
 title: EAS Simulators
 sidebarTitle: EAS Simulators
 description: Run mobile targets on EAS Simulators' hosted iOS simulators and Android emulators with the easSimulators() device provider from @e2e-dev/eas.
+icon: "/images/icons/expo.svg"
 ---
 
 `easSimulators()` from `@e2e-dev/eas` is a

package/docs/integrations/index.mdx

@@ -2,6 +2,7 @@
 title: Integrations
 sidebarTitle: Overview
 description: Official integrations with hosted services, one package per service.
+icon: "plug"
 ---
 
 Official integrations connect e2e to hosted services through the engines'

package/docs/integrations/kernel.mdx

@@ -2,6 +2,7 @@
 title: Kernel browsers
 sidebarTitle: Kernel
 description: Run web targets in Kernel's hosted Chromium with the kernel() browser provider from @e2e-dev/kernel.
+icon: "/images/icons/kernel.svg"
 ---
 
 `kernel()` from `@e2e-dev/kernel` is a
@@ -60,7 +61,7 @@ web({
 ```
 
 Each attempt's window then opens maximized, and the page
-[fills it](/viewports#fill-the-window): 1920 by 993 on a 1920 by 1080 screen,
+[fills it](/web#fill-the-window): 1920 by 993 on a 1920 by 1080 screen,
 after the tab strip and address bar. With a fixed web `viewport`, the page is
 emulated at that size inside a smaller window, so Kernel's live view shows it
 cut off or in part of the window.
@@ -90,7 +91,7 @@ cookies and storage are not there.
 that browser's default context, on its own first tab, so a `profile` applies
 and the live view shows one tab. It costs a browser start per test and
 carries the limits of a [per-attempt lease](/browser#hosted-browsers): no
-`headers`, `basicAuth`, or `userAgent`, no `app.clearState()`, and no
+`headers`, `basicAuth`, `userAgent`, `locale`, or `timezoneId`, no `app.clearState()`, and no
 [sessions](/authentication), which fail the run before any test.
 
 ## Recordings

package/docs/migrate/cypress.mdx

@@ -1,8 +1,31 @@
 ---
 title: From Cypress
 description: Replace Cypress command chains with async tests and keep your data-cy attributes.
+icon: "/images/icons/cypress.svg"
 ---
 
+import { SetupPrompt } from '../snippets/setup-prompt-card.jsx';
+
+export const migrationPrompt = `Migrate this project's Cypress tests to e2e, one spec at a time. Docs: \`https://e2e.tester.army/docs/migrate/cypress.md\`
+
+1. Read the migration guide above. It maps Cypress config, commands, and assertions to e2e.
+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 \`cypress.config.*\` into the e2e config: \`baseUrl\` and the dev server command become the target's \`app\`, and if the specs select by \`data-cy\`, set \`web({ testIdAttribute: 'data-cy' })\` so \`screen.getByTestId\` reads it. Keep Cypress installed while both suites run.
+6. Install dependencies.
+7. List the Cypress end-to-end specs and ask me which one to move first. Suggest one that breaks often or waits with \`cy.wait(ms)\`. Component tests have no e2e equivalent; leave them in Cypress.
+8. Rewrite that spec as a \`.e2e.ts\` file under \`tests/\` (e2e runs \`tests/**/*.e2e.ts\` by default), with one awaited call per line and no chains. \`cy.contains\` matches a substring and e2e queries match the whole text, so pass \`{ exact: false }\` where the spec relied on a fragment. Replace each \`cy.wait(ms)\` with an assertion on the state the test waits for. Move \`cy.task\`, \`cy.exec\`, and \`cy.request\` into plain Node code, and custom commands into functions or fixtures.
+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 Cypress spec until I confirm it can go.
+11. Summarize which tests moved, which stayed in Cypress, and why.`;
+
+<SetupPrompt>
+
+<Prompt description={migrationPrompt} children={migrationPrompt} actions={["copy", "cursor"]} />
+
+</SetupPrompt>
+
 e2e tests run in Node. Use `await` for UI actions and call Node functions
 directly for work previously handled by `cy.task`. Both suites can stay in
 the project while you migrate one spec at a time.
@@ -15,7 +38,7 @@ for the agent calls shown below.
 | Cypress | e2e |
 | --- | --- |
 | `baseUrl` | `app: { url }` on the target |
-| `start-server-and-test` | `app: { url, command }`, see [Starting your app](/starting-your-app) |
+| `start-server-and-test` | `app: { url, command }`, see [Starting your app](/web#starting-your-app) |
 | `viewportWidth`, `viewportHeight` | `web({ viewport })` |
 | `data-cy` selectors | `web({ testIdAttribute: 'data-cy' })`, then `screen.getByTestId` |
 | `retries` | `retries` |
@@ -115,8 +138,8 @@ Start with a spec that often breaks and whose fixed `cy.wait` calls can
 become assertions on the condition the test needs.
 
 <CardGroup cols={2}>
-  <Card title="Writing tests" icon="pen-to-square" href="/writing-tests">
-    Goals, checks, extraction, and the deterministic APIs.
+  <Card title="Core concepts" icon="pen-to-square" href="/core-concepts">
+    Goals, assertions, and locators instead of scripted selectors.
   </Card>
   <Card title="Working with the browser" icon="globe" href="/browser">
     Routes, dialogs, downloads, iframes, and page evaluation.

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="Writing tests" icon="pen-to-square" href="/writing-tests">
-    Goals, checks, extraction, and the deterministic APIs.
+  <Card title="Core concepts" icon="pen-to-square" href="/core-concepts">
+    Goals, assertions, and locators instead of scripted selectors.
   </Card>
 </CardGroup>