@e2edev/e2e 0.10.0 → 0.12.0

package/skills/e2e/SKILL.md

@@ -18,6 +18,7 @@ target names an engine, `@e2edev/playwright` for browsers or
 import type { E2EConfig } from '@e2edev/e2e';
 import { createAgent } from '@e2edev/e2e/agent';
 import { playwright } from '@e2edev/playwright';
+import { gateway } from 'ai';
 
 export default {
   targets: [
@@ -28,8 +29,13 @@ export default {
       }),
     },
   ],
-  // Only needed for agent.* steps; the model comes from E2E_MODEL.
-  agents: { default: createAgent({ system: 'You are a thorough QA agent. Verify every outcome on screen.' }) },
+  // Only needed for agent.* steps. The model is an AI SDK instance; gateway() from 'ai' reads AI_GATEWAY_API_KEY.
+  agents: {
+    default: createAgent({
+      model: gateway('openai/gpt-5.4-mini'),
+      system: 'You are a thorough QA agent. Verify every outcome on screen.',
+    }),
+  },
 } satisfies E2EConfig;
 ```
 
@@ -58,7 +64,9 @@ one. Without them, the installed CLI prints the same text:
 | `writing-tests` | [references/writing-tests.md](references/writing-tests.md) | Writing or fixing tests: fixtures, locators, actions, matchers, sign-in sessions, the `web` fixture |
 | `agent` | [references/agent.md](references/agent.md) | Adding `agent.*` steps, picking a model, cost and budgets, the trace cache |
 | `running` | [references/running.md](references/running.md) | CLI flags, reporters, `.e2e/report.json`, exit codes, CI |
+| `explore` | [references/explore.md](references/explore.md) | Exploring an app toward a goal without a test file: `e2e explore`, its budgets, verdict, and `run.explore` |
 | `debugging` | [references/debugging.md](references/debugging.md) | A run failed: error codes and their fixes, `--headed`, `--debug`, `--ai-trace` |
+| `mcp` | [references/mcp.md](references/mcp.md) | Driving the live app from a coding agent over MCP: `e2e mcp`, its tools, and the explore-then-write loop |
 
 ## Workflow
 
@@ -67,13 +75,15 @@ one. Without them, the installed CLI prints the same text:
    there: follow `setup`.
 2. Learn the screens you will drive before writing a test: routes, labels,
    roles, button text. Semantic locators need the accessible names the app
-   renders, so read the templates or components, or open the page with
-   `--headed`.
+   renders, so read the templates or components, open the page with
+   `--headed`, or drive the live app through the `e2e mcp` server when it is
+   registered (topic `mcp`): `open_session`, `observe`, and `locate` show the
+   exact names and check a locator before you write it.
 3. Write `tests/<feature>.e2e.ts`. Deterministic steps first. One `agent.act`
    per goal where the flow varies, and an `expect` on its outcome right after.
 4. Run one file: `npx --no-install e2e run tests/<feature>.e2e.ts`. Agent
-   steps need `E2E_MODEL=provider/model-id` and `E2E_MODEL_API_KEY` in the
-   environment; deterministic tests need neither.
+   steps need a model in the config and its provider's key in the environment
+   (`AI_GATEWAY_API_KEY` for `gateway()`); deterministic tests need neither.
 5. Read the failure: the reporter prints the error code, the message, and a
    code frame; `.e2e/report.json` has every step and artifact path. Fix the
    locator, the expectation, or the app. Never add a sleep.

package/skills/e2e/references/agent.md

@@ -6,18 +6,19 @@ transcript between calls. Deterministic tests never load a model.
 
 ## Configure a model
 
-Agents live under `agents` by name; `default` is the one tests use, `e2e run --agent <name>` re-points that default, a test or describe pins one with `{ agent: 'name' }`, and any `agent.*` call can name one with `{ agent: 'name' }` (innermost wins). There is no default model. Pick one of three shapes for an entry:
+Agents live under `agents` by name; `default` is the one tests use, `e2e run --agent <name>` re-points that default, a test or describe pins one with `{ agent: 'name' }` or several with `{ agent: ['buyer', 'admin'] }` (the test runs once per agent, one result each, tagged `[admin]` in the terminal and `agent` in the report), and any `agent.*` call can name one with `{ agent: 'name' }` (innermost wins). `--agent buyer,admin` runs every unpinned test once per agent; on a pinned list it narrows to the names both give and never overrides a pin it does not name. A signed-in persona pairs the pin with a `session`, one per describe block, so a loop over describe blocks sweeps signed-in personas. There is no default model. Pick one of three shapes for an entry:
 
 ```ts
 // e2e.config.ts
 import { createAgent } from '@e2edev/e2e/agent';
+import { gateway } from 'ai';
 
 export default {
-  // 1. The built-in agent; the model comes from E2E_MODEL at run time.
-  agents: { default: createAgent({ system: 'You are a thorough QA agent. Verify every outcome on screen.' }) },
+  // 1. The built-in agent with an AI SDK model: gateway() from 'ai' is the Vercel AI Gateway and reads AI_GATEWAY_API_KEY.
+  agents: { default: createAgent({ model: gateway('openai/gpt-5.4-mini'), system: 'You are a thorough QA agent. Verify every outcome on screen.' }) },
 
-  // 2. An options block: a gateway model string plus project vocabulary.
-  // agents: { default: { model: 'anthropic/claude-sonnet-4.5', context: 'A billing dashboard. Plans are Free, Team, and Pro.' } },
+  // 2. An options block: a model plus project vocabulary. openrouter() from '@openrouter/ai-sdk-provider' reads OPENROUTER_API_KEY.
+  // agents: { default: { model: openrouter('anthropic/claude-sonnet-4.5'), context: 'A billing dashboard. Plans are Free, Team, and Pro.' } },
 
   // 3. A live AI SDK model instance for a provider called directly.
   // agents: { default: createAgent({ model: openai('gpt-5.4-mini') }) },
@@ -25,21 +26,25 @@ export default {
 ```
 
 ```bash
-E2E_MODEL=anthropic/claude-sonnet-4.5 E2E_MODEL_API_KEY=... npx --no-install e2e run
+AI_GATEWAY_API_KEY=... npx --no-install e2e run
 ```
 
-- A `provider/model-id` string is routed through the Vercel AI Gateway; one
-  `E2E_MODEL_API_KEY` (or `AI_GATEWAY_API_KEY`) reaches every provider.
-- With no `agents` key at all, the built-in agent still runs as `default` and takes its
-  model from `E2E_MODEL`. Use `createAgent` for a `system` prompt, tools, or
-  a pinned model.
+- The model is always an AI SDK instance the config constructs; the runner
+  implies no gateway and reads no model variable. `gateway()` from `ai` is the
+  Vercel AI Gateway, `openrouter()` from `@openrouter/ai-sdk-provider` is
+  OpenRouter, `createOpenAICompatible({ baseURL }).chatModel()` from
+  `@ai-sdk/openai-compatible` is any /v1 chat endpoint (Ollama, vLLM), and a
+  provider's own package (`openai()`) calls it directly. Each reads its own
+  key variable. A string in a model slot is `INVALID_CONFIG`.
+- With no model anywhere, acquiring `agent` is `MODEL_UNAVAILABLE`. Use
+  `createAgent` for the model, a `system` prompt, and tools.
 - `ai@^7` must be installed for any `agent.*` step; the runner loads it
   lazily and fails without it.
 - `context` in the config and `agentContext` on a test or group add trusted
   project vocabulary to every prompt.
-- `visionModel` (or `E2E_VISION_MODEL`) serves the calls that send pixels.
+- `visionModel` serves the calls that send pixels.
 - The model passed to `createAgent({ model })` is the one model for every
-  `agent.*` call, `act` and the judgments alike, and outranks `E2E_MODEL`.
+  `agent.*` call, `act` and the judgments alike.
   An agent `model` naming a different model is `INVALID_CONFIG`.
 - Missing model or key: checked once per run when the first test acquires
   the `agent` fixture. One run-level `MODEL_UNAVAILABLE` (exit 2) stops the
@@ -217,12 +222,12 @@ arbitrary tool result JSON or other fields are preserved.
   can be the `agent`; the runner still owns observations, actions, budgets,
   and the report.
 
-Full reference: https://e2e-docs.vercel.app/agents
+Full reference: https://e2e.mintlify.app/agents
 
 ## In CI
 
 Deterministic tests gate merges; agentic tests are opt-in. Keep them in a
 separate config (`e2e.agent.config.ts` with its own `tests` glob and a larger
-`timeout`), run them on a schedule or `workflow_dispatch`, and pass the model
-through `env: { E2E_MODEL, E2E_MODEL_API_KEY }` from CI variables and
+`timeout`), run them on a schedule or `workflow_dispatch`, and pass the key
+the config's model reads (`env: { AI_GATEWAY_API_KEY }` for `gateway()`) from
 secrets.

package/skills/e2e/references/debugging.md

@@ -36,9 +36,10 @@ jq '.run.results[] | select(.status != "passed") | .attempts[-1]
 | `ASSERTION_FAILED` | The expectation is wrong, or the state settles later than 5 s; for `agent.assert`, the judgment was false (explanation in the report) | Compare with the actual text in the report or screenshot; `{ timeout }` on the matcher; rewrite the question |
 | `ACTION_FAILED` | Element not actionable (covered, disabled, detached) or an operation timed out | Wait on the right condition with `expect` first; close overlays; check `actionTimeout` |
 | `TEST_TIMEOUT` | The attempt exceeded `timeout` (120 s) | Split the test, or raise `timeout` for slow flows and agent steps |
-| `MODEL_UNAVAILABLE` | No model (`createAgent({ model })`, `agent.model`, or `E2E_MODEL`), no key, or an unknown provider. Reported once for the run under `run.errors`; the run stops | Export `E2E_MODEL=provider/model-id` and `E2E_MODEL_API_KEY`, or pass a model to `createAgent`; confirm the model id |
+| `MODEL_UNAVAILABLE` | No model: neither `createAgent({ model })` nor `agent.model` holds an AI SDK instance. Reported once for the run under `run.errors`; the run stops | Construct one in the config, e.g. `gateway('openai/gpt-5.4-mini')` from `ai`, and export the key its provider reads (`AI_GATEWAY_API_KEY`) |
 | `MODEL_PROVIDER_FAILED` | Network, 5xx, rate limit, or no credits after the transport retries | Check the key and the quota; retry; exit code 3 |
 | `STEP_TIMEOUT`, `STEP_BUDGET_EXHAUSTED` | The goal was too big or ambiguous, or the provider slow | Split the goal, use on-screen wording, add `context`, raise `timeout` and `actionTimeout`, `--debug` to read the transcript |
+| `CONTEXT_OVERFLOW` | The screen plus the step's history did not fit the model's context window, even after the loop shrank the history and retried once | Lower `agent.maxObservationBytes`, split the step, or pick a model with a larger window |
 | `POLICY_DENIED` | Navigation outside `allowedOrigins`; a `Secret` given to a sink that is not a password field; reading a secure field | Add the origin to `allowedOrigins`; fill secrets only into password inputs; assert the outcome instead of the value |
 | `UNSUPPORTED_CAPABILITY` | A fixture the engine does not contribute (`web` on a device), `schema` or `vision` on `act`, an action the surface lacks | Declare `requires: ['web']`; drop the option; use a supported action |
 | `SESSION_UNAVAILABLE`, `SESSION_CONTRACT` | `session: 'x'` with no setup saving `x`; a setup that did not save every declared name | Add or fix the `test.setup` |

package/skills/e2e/references/explore.md

@@ -0,0 +1,83 @@
+# Exploring without a test
+
+`e2e explore` runs the agent against the app with a goal instead of a test
+file. Use it to see what the agent can do with an app before tests exist, to
+hunt for regressions on a branch, or to find what is worth turning into a
+test. It needs a config with a target and an agent that holds a model,
+nothing else.
+
+```bash
+npx --no-install e2e explore                                         # goal: "Explore the app and find bugs"
+npx --no-install e2e explore 'Explore checkout like a first-time buyer and report anything off'
+npx --no-install e2e explore --target web --max-steps 4 --headed
+npx --no-install e2e explore 'Hunt for broken forms' --video
+```
+
+## What a run does
+
+1. Opens the app on the target's URL.
+2. Plans one step: a structured model call reads the goal, the steps and
+   findings so far, and the current screen, and answers with a title and a
+   concrete charter for one flow, or decides the goal is covered.
+3. Runs the charter as an `agent.act()` step with the project's tools plus
+   `report_finding`. The agent reports each defect the moment it has evidence:
+   title, `issue` or `warning`, severity 1 to 5, expected, actual, reproduction
+   steps. The runner adds the path and a redacted screenshot.
+4. Repeats until the planner finishes, the step limit, the clock, or three
+   failed or blocked steps in a row that reported nothing; then asks for a closing assessment.
+
+A failed step does not end the run: it is recorded, and only findings the
+agent reported count toward the verdict. A step that hits its action or time
+budget ended at its limit and counts as neither. Configured `credentials`
+reach the explorer as step secrets: the planner knows the account names and
+usernames, and the agent fills passwords with `type_secret` by name.
+
+## Flags
+
+| Flag | Default | Effect |
+| --- | --- | --- |
+| `[goal]` | `Explore the app and find bugs` | One quoted sentence: the area and the posture. |
+| `--target <id>` | first configured target | The one target to explore. |
+| `--agent <name>` | `default` | Build the explorer from another configured agent (`agents.<name>`). |
+| `--max-steps <n>` | 8 (1 to 12) | Exploration steps at most. |
+| `--timeout <ms>` | 600000 (180000 to 900000) | Wall clock; the last minute is for the assessment. |
+| `--headed`, `--reporter`, `--artifacts`, `--debug`, `--ai-trace`, `--video` | as `run` | Same meaning as for `e2e run`. |
+
+Per-step action and model-call budgets default to 40 each; `agent.maxSteps`
+and `agent.maxModelCalls` in the config override them. The trace cache is off
+and retries are zero for the run.
+
+## Reading the result
+
+Exit code `0`: steps ran and no `issue` was reported (warnings allowed). Exit
+code `1`: at least one `issue`, or no step ran and nothing was found (the run
+is `blocked`). `2` and `3` as for `run`.
+
+The terminal prints each step live and, under the summary, `Explored`,
+`Findings`, one row per finding sorted by severity, and `Assessment`.
+`.e2e/report.json` has the record under `run.explore`:
+
+```json
+{
+  "goal": "...",
+  "budgets": { "maxSteps": 8, "timeoutMs": 600000 },
+  "ended": "finished | step-limit | time | stuck | aborted",
+  "summary": "the closing assessment",
+  "steps": [{ "index": 1, "title": "...", "instruction": "...", "status": "passed | failed | blocked | exhausted", "summary": "...", "startedAt": "...", "durationMs": 0 }],
+  "findings": [{ "index": 0, "step": 1, "kind": "issue", "severity": 4, "title": "...", "expected": "...", "actual": "...", "reproduction": ["..."], "path": "/cart", "artifactId": "<attempt id>:artifact:2", "reportedAt": "..." }]
+}
+```
+
+`artifactId` names the evidence screenshot among the attempt's `artifacts` in
+`run.results[0]`, where its path, size, and digest are.
+
+Turn a finding into a test: its `reproduction` steps are the `agent.act()`
+instructions or `screen.*` actions, and `expected` is the assertion.
+
+## When it does not fit
+
+An agent built with `createAgent({ tools, system })` in the config lends its
+tools and guidance to the explorer; a hand-rolled `StepExecutor` is replaced by
+the built-in agent for the run, with a notice on stderr. Findings are the
+model's claims plus evidence, not verified reproductions: read `actual` against
+the screenshot before filing a bug.

package/skills/e2e/references/mcp.md

@@ -0,0 +1,88 @@
+# Driving the app over MCP
+
+`e2e mcp` serves a project's live app to a coding agent over MCP (stdio).
+It gives the agent the same hands the testing agent has on the app: look at
+a screen before writing a test, and check a locator before committing to it.
+Running tests and reading a failed run stay on the CLI (topics `running` and
+`debugging`).
+
+## Setup
+
+The server ships with `@e2edev/e2e`. `e2e init` offers to register it; by
+hand:
+
+```bash
+claude mcp add e2e -- npx --no-install e2e mcp          # Claude Code
+```
+
+Or declare it in the client's project config (`.mcp.json` for Claude Code,
+`.cursor/mcp.json` for Cursor, `.vscode/mcp.json` for VS Code):
+
+```json
+{ "mcpServers": { "e2e": { "command": "npx", "args": ["--no-install", "e2e", "mcp"] } } }
+```
+
+Flags: `--config <path>` names the default config file, `--target <name>`
+fixes the target every session opens on, `--headless` hides the browser or
+simulator (sessions are headed by default outside CI, so the developer can
+watch).
+
+## Tools
+
+The server has four tools, and the list never changes. Everything a session
+can do is a catalog behind `call`.
+
+| Tool | Does |
+| --- | --- |
+| `open_session` | Loads the config (`config` names another file; default the nearest `e2e.config.ts`), starts the declared app command if any, boots the engine, opens the app URL, and returns the session id, the catalog, and the first observation. `target` is required when the config declares several. One session at a time. |
+| `tools` | The catalog: one line per tool with its argument names (`?` marks optional), the first sentence of its description, and `[read-only]` where it changes nothing. `tools {tool}` shows one tool's full description and the JSON Schema of its arguments. |
+| `call` | Runs one catalog tool: `call {tool: "tap", args: {target: "n42"}}`. Arguments are checked against the tool's schema first; a wrong one fails with `INVALID_ARGUMENT` naming the field. |
+| `close_session` | Ends the attempt, disposes the engine, stops the app processes the session started. |
+
+The catalog, per session:
+
+| Catalog tool | Does |
+| --- | --- |
+| `observe` | A fresh observation: one node per line as `#id role "name" ...`, plus the current path. |
+| `tap`, `type`, `press`, `select`, `scroll`, `navigate` | The grammar verbs, exactly as the testing agent gets them. Each reports what changed on screen; `observe` shows the whole screen. A verb the engine cannot honor is not listed and fails with `UNSUPPORTED_CAPABILITY`. |
+| `type_secret` | Fills a configured credential's password into a secure field by credential name; the plaintext never reaches the agent. Listed when the config declares `credentials`. |
+| `locate` | Tries a semantic locator (`role` + `name`, `text`, `label`, `placeholder`, `testId`, `exact`) and returns how many nodes match, which, and the `screen.*` call to write. |
+| `screenshot` | The masked pixels as an image, withheld once a secret was filled in the session. |
+| Project tools | Every `defineTool` passed to `createAgent({ tools })` that applies to the target's platform, under its own name; an engine pack such as `agentDeviceTools` adds `open_app`, `swipe`, `type_text`, `alert`. |
+
+Resources: `e2e://guide` and `e2e://guide/<topic>` hold this skill.
+
+## Workflow
+
+1. `open_session`, then `call {tool: "observe"}` and act until the screen you
+   want to test is in front of you. Node ids are valid only for the newest
+   observation; an action reports what changed, so observe again before
+   using new ids. The opening text lists every tool with its arguments;
+   `tools {tool}` when you need the full contract.
+2. `call {tool: "locate", args: {...}}` for each locator you intend to write.
+   One match: use the printed `screen.getByRole(...)` call. Zero or several:
+   adjust before writing the test, the same failure would hit the test as
+   `LOCATOR_NOT_FOUND` or `LOCATOR_AMBIGUOUS`.
+3. Write `tests/<feature>.e2e.ts` (topic `writing-tests`). Deterministic steps
+   where you saw exact names; `agent.act` where the flow varies.
+4. Run it from the shell: `npx --no-install e2e run tests/<feature>.e2e.ts`,
+   read the failure (topic `debugging`), fix, repeat.
+5. `close_session` when you are done exploring; an idle session closes on its
+   own after 30 minutes and never outlives 4 hours. To look at another
+   project or config, `open_session {config: "path/to/e2e.config.ts"}`; no
+   restart needed.
+
+## Rules
+
+- Sessions enforce the same policy as tests: navigation stays inside the
+  engine's allowed origins, secrets fill only through `type_secret`, and
+  pixels are withheld once a secret is on screen.
+- Nothing a session does is recorded as a test or into the trace cache. A
+  session is for looking and trying; the test is what you write afterwards.
+- A run from the shell and a live session can share the app only if the
+  engine's `command` uses `reuseExisting`; otherwise close the session before
+  running.
+- `TARGET_REQUIRED`: pass `target` to `open_session` or start with `--target`.
+  `NO_SESSION`: call `open_session` first. `SESSION_OPEN`: one is already
+  open; use it or `close_session`. `UNKNOWN_TOOL`: the name is not in this
+  session's catalog; the message lists what is.

package/skills/e2e/references/running.md

@@ -4,10 +4,12 @@
 
 ```bash
 npx --no-install e2e run [files...] [options]   # run tests
+npx --no-install e2e explore [goal] [options]   # explore the app toward a goal, no test file (see the explore topic)
 npx --no-install e2e list [files...] [options]  # print what run would select, without running
 npx --no-install e2e init [--yes]               # scaffold a project, refresh the agent skill
-npx --no-install e2e guide [topic]              # print this skill: setup, writing-tests, agent, running, debugging
+npx --no-install e2e guide [topic]              # print this skill: setup, writing-tests, agent, running, explore, debugging, mcp
 npx --no-install e2e cache ls|clear|stats       # read or empty the trace cache
+npx --no-install e2e mcp [--target <name>]      # serve the project to a coding agent over MCP (topic mcp)
 npx --no-install e2e telemetry [disable|enable] # anonymous usage telemetry: status, or the switch
 ```
 
@@ -20,7 +22,7 @@ npx --no-install e2e telemetry [disable|enable] # anonymous usage telemetry: sta
 | `--target <ids>` | Comma-separated target names. Only selected targets start app commands and services; unknown names fail before startup. |
 | `--tag <tag>` | Repeatable tag filter; `--tag-mode all` requires every tag. |
 | `--headed` | Visible browser or simulator when the engine supports it. |
-| `--agent <name>` | Run with another configured agent (`agents.<name>`); default is `agents.default`. |
+| `--agent <names>` | Run unpinned tests as other configured agents (`agents.<name>`), comma-separated or repeated; several names run each such test once per agent. Default is `agents.default`. |
 | `--workers <n>`, `--retries <n>` | Override the resolved values. |
 | `--reporter <ids>` | `list`, `json`, `junit`, comma-separated. `json` cannot combine with `list`. |
 | `--artifacts <dir>` | Artifact root, default `.e2e/artifacts`. |
@@ -70,7 +72,7 @@ recorded flow is stale — `--no-cache` only skips the cache for one run.
 
 - `list` (default): one line per file and target, a `Failed Tests` section
   with each error, its code, the failing line and a code frame, then a
-  summary (`Test Files`, `Tests`, `AI`, `Start at`, `Duration`, `Report`); setup steps (a first-run browser download, each service and app command) print above the tests and stay out of `Duration` or are split out of it as `(startup …)`.
+  summary (`Test Files`, `Tests`, `AI`, `Cache` when the trace cache was on: agent steps `replayed` whole, `handed off` to the model part-way, or `missed`, `Start at`, `Duration`, `Report`); setup steps (a first-run browser download, each service and app command) print above the tests and stay out of `Duration` or are split out of it as `(startup …)`.
 - `.e2e/report.json` is written on every run whatever the reporters:
   `run.status`, `run.exitCode`, `run.errors[]` (run-level failures such as
   `APP_UNREACHABLE`), and `run.results[]`, one per test and target, with
@@ -155,5 +157,5 @@ jobs:
 - Start the app through the engine's `command`; the runner tears it down on
   every exit path.
 - Agentic suites: a separate config, run on `schedule` or
-  `workflow_dispatch`, `E2E_MODEL` as a CI variable and `E2E_MODEL_API_KEY`
-  as a secret, never a required check.
+  `workflow_dispatch`, the key the config's model reads (`AI_GATEWAY_API_KEY`
+  for `gateway()` from `ai`) as a secret, never a required check.

package/skills/e2e/references/setup.md

@@ -21,14 +21,15 @@ pnpm dlx @e2edev/e2e@beta init  # pnpm
 When `@e2edev/e2e` is already installed, run `npx --no-install e2e init`
 instead, so the installed version scaffolds.
 
-The wizard asks for the engine (Playwright by default; None and agent-device
-are the alternatives), whether to enable AI testing (adds `ai@^7.0.0` and
-`createAgent` to the config), which agent directories receive this skill
+The wizard asks for the engine (Web with Playwright by default; Mobile with
+agent-device and None are the alternatives), which model gateway agent steps
+use (adds AI SDK v7 and the provider package), which agent directories receive this skill
 (`.agents/skills/` and `.claude/skills/`), a confirmation of the files it
 will write, and whether to install. `--yes` skips every prompt (use it from
-scripts and from a shell without a TTY): Playwright, AI on, no installation,
-skill in both directories. The closing line prints the run command,
-`APP_URL=http://localhost:3000 npx --no-install e2e run` for Playwright, and
+scripts and from a shell without a TTY): Playwright, the Vercel AI Gateway,
+no installation, skill in both directories. The closing line prints the run
+command through the project's package manager,
+`APP_URL=http://localhost:3000 npm run test:e2e` for Playwright under npm, and
 suggests a `tsconfig.json` when the project has none.
 
 Init writes `package.json` (a private ESM package when missing; otherwise
@@ -56,6 +57,7 @@ unknown keys are `INVALID_CONFIG`.
 import type { E2EConfig } from '@e2edev/e2e';
 import { createAgent } from '@e2edev/e2e/agent';
 import { playwright } from '@e2edev/playwright';
+import { gateway } from 'ai';
 
 export default {
   tests: 'tests/**/*.e2e.ts',
@@ -67,8 +69,13 @@ export default {
       }),
     },
   ],
-  // Only for agent.* steps. The model comes from E2E_MODEL unless set here.
-  agents: { default: createAgent({ system: 'You are a thorough QA agent. Verify every outcome on screen.' }) },
+  // Only for agent.* steps. The model is an AI SDK instance; gateway() from 'ai' reads AI_GATEWAY_API_KEY.
+  agents: {
+    default: createAgent({
+      model: gateway('openai/gpt-5.4-mini'),
+      system: 'You are a thorough QA agent. Verify every outcome on screen.',
+    }),
+  },
   credentials: {
     admin: { username: 'admin@example.test', password: process.env.ADMIN_PASSWORD ?? '' },
   },
@@ -86,7 +93,7 @@ export default {
 | `workers` | half the cores, `1` in CI | Test files run in parallel across workers, at most the `workers` the engine declares per target (a device target: one per device). |
 | `reporters` | `['list']` | `list`, `json`, `junit`, and reporter objects (`{ name, onEvent?, onRunFinished? }`) that receive the finished run. `json` excludes `list`; `--reporter` keeps the objects. |
 | `cache` | `'read-write'`, `'read-only'` in CI | The trace cache for `agent.act`; `'off'` disables it. |
-| `agents` | `{ default: built-in }` | Agents by name. `default` is what tests run with; `e2e run --agent <name>` runs with another. Each entry is `createAgent(...)`, an options block `{ model, context, visionModel, maxSteps, maxModelCalls, vision, providerOptions }`, or a custom `StepExecutor`. Omitted, the built-in agent runs with `E2E_MODEL`. |
+| `agents` | `{ default: built-in }` | Agents by name. `default` is what tests run with; `e2e run --agent <name>` runs with another. Each entry is `createAgent(...)`, an options block `{ model, context, visionModel, maxSteps, maxModelCalls, vision, providerOptions }`, or a custom `StepExecutor`. `model` is an AI SDK instance; without one anywhere, acquiring `agent` is `MODEL_UNAVAILABLE`. |
 | `credentials` | `{}` | Named `{ username, password, allowedOrigins? }` entries; `password` may be a function returning the value. |
 | `screen.testIdAttribute` | `'data-testid'` | Attribute read by `getByTestId`. |
 | `artifacts` | `['screenshot', 'trace']` | Kinds to keep (`screenshot`, `trace`, and the opt-in `video`), or `{ kinds, store, video }`; `video: { retain: 'on-failure' }` keeps only the recordings of attempts that did not pass. |
@@ -184,10 +191,7 @@ or read the address from the environment:
 
 | Variable | Effect |
 | --- | --- |
-| `E2E_MODEL` | `provider/model-id` for `agent.*` steps when the config sets no model. Routed through the Vercel AI Gateway. |
-| `E2E_MODEL_API_KEY` | Credential for that model. `AI_GATEWAY_API_KEY` is the fallback. |
-| `E2E_MODEL_ENDPOINT` | Any OpenAI-compatible endpoint URL for that model; the gateway is the default. HTTPS unless loopback. The agent's `model.endpoint` wins. |
-| `E2E_VISION_MODEL` | Model for calls with `vision`; falls back to the main model. |
+| `AI_GATEWAY_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, ... | Read by the provider package the config constructs the model with (`gateway()` from `ai`, `openrouter()`, `openai()`), not by the runner. The runner reads no model variable; the model is always an AI SDK instance in the config. |
 | `E2E_USER_<NAME>_USERNAME`, `E2E_USER_<NAME>_PASSWORD` | Override `credentials.<name>`. `<NAME>` is the credential name uppercased, other characters as `_`. |
 | `CI` | Turns on CI defaults: `retries: 1`, `workers: 1`, `test.only` rejected, cache read-only, `reuseExisting` ignored. |
 | `E2E_TELEMETRY_DISABLED`, `DO_NOT_TRACK` | Turn anonymous usage telemetry off; `e2e telemetry disable` saves the same choice. `E2E_TELEMETRY_DEBUG=1` prints each event instead of sending it. |