@testdriverai/agent 7.11.150-canary → 7.11.151-canary

package/ai/skills/testdriver-agent/SKILL.md

@@ -4,23 +4,23 @@ description: How the TestDriver agent behaves on GitHub issues, pull requests, a
 ---
 <!-- Generated from agent.mdx. DO NOT EDIT. -->
 
-The TestDriver agent is an AI teammate that lives in your GitHub repository. It's
-**code review that runs your app** — instead of only reading a diff and guessing
-what might break, it starts a real sandbox, drives the real app, and reports what
-actually happens.
+The TestDriver agent is an AI teammate in your GitHub repository. It is
+**code review that runs your app**. It does not only read a diff and guess
+what can break. It starts a real sandbox, controls the real app, and reports what
+really happens.
 
 ## Scope: it only builds and maintains tests
 
-The agent is focused. The one thing it does is **write, debug, fix, and maintain
-automated tests** with TestDriver, and review pull requests by writing and running
-a test against the change. It will politely decline off-scope work — it won't edit
-your application code, fix product bugs, answer unrelated programming questions, or
+The agent has one purpose. It does one thing: it **writes, debugs, fixes, and keeps
+automated tests** with TestDriver. It reviews pull requests. It writes and runs
+a test against the change. It does not do work that is not in scope. It does not edit
+your application code, fix product bugs, answer other programming questions, or
 act as a general coding assistant.
 
 ## How it behaves depends on the surface
 
-The agent reacts to three different GitHub surfaces, and its behavior is
-noticeably different on each.
+The agent reacts to three different GitHub surfaces. Its behavior is
+different on each one.
 
 | Surface | Trigger | What it does |
 |---------|---------|--------------|
@@ -30,13 +30,13 @@ noticeably different on each.
 
 ## Pull requests — automatic code review
 
-When a pull request is **opened**, the agent reviews it automatically — nobody has
+When a pull request is **opened**, the agent reviews it automatically. Nobody has
 to ask.
 
-- **The review is the deliverable, not chatter.** An automatic review is
-  unsolicited, so the agent stays quiet while it works and posts a **single review
-  comment** at the end rather than scattering inline threads across the diff or
-  narrating each step.
+- **The review is the deliverable, not chatter.** No person asks for an automatic review.
+  Thus the agent stays quiet while it works. It posts a **single review
+  comment** at the end. It does not put many inline threads across the diff. It does not
+  tell each step.
 - **It runs the change when it can.** Its default first move is to start a session,
   work out what the PR changes from a user's point of view, and write and run a
   TestDriver test that exercises exactly that. A bug it *watched happen* is far

package/ai/skills/testdriver-aws-setup/SKILL.md

@@ -4,7 +4,7 @@ description: Deploy TestDriver on your AWS infrastructure using CloudFormation
 ---
 <!-- Generated from aws-setup.mdx. DO NOT EDIT. -->
 
-This guide walks you through setting up self-hosted TestDriver instances on AWS. By the end, you'll have fully automated test infrastructure that spawns and terminates instances on-demand.
+This guide helps you to set up self-hosted TestDriver instances on AWS. At the end, you have automated test infrastructure. It starts and stops instances when you need them.
 
 ```mermaid
 graph LR
@@ -16,13 +16,13 @@ graph LR
 
 ## How It Works
 
-TestDriver automatically manages AWS EC2 instances for your tests:
+TestDriver manages the AWS EC2 instances for your tests automatically:
 
-1. **Deploy CloudFormation** — One-time infrastructure setup
-2. **Configure Vitest** — Add one line to your config
-3. **Run Tests** — Instances spawn automatically, run tests, and terminate
+1. **Deploy CloudFormation**. Set up the infrastructure one time.
+2. **Configure Vitest**. Add one line to your config.
+3. **Run Tests**. The instances start automatically, run the tests, and stop.
 
-That's it! No manual instance management needed.
+That is all. You do not need to manage the instances by hand.
 
 # Quickstart
 

package/ai/skills/testdriver-cache/SKILL.md

@@ -6,18 +6,18 @@ description: Speed up tests with screenshot-based caching
 
 ## Overview
 
-The cache system speeds up repeated test runs by comparing screenshots to cached results. When the screen hasn't changed significantly, cached element positions are reused instead of making an AI call.
+The cache system makes repeated test runs faster. It compares screenshots to cached results. When the screen did not change much, TestDriver uses the cached element positions again. It does not make an AI call.
 
-Cache works at two levels:
-- **Screen cache** — pixel diff comparison between the current screenshot and the cached screenshot
-- **Element cache** — OpenCV template matching to verify the cached element position is still correct
+The cache works at two levels:
+- **Screen cache**: a pixel diff comparison between the present screenshot and the cached screenshot
+- **Element cache**: OpenCV template matching to make sure that the cached element position is still correct
 
 ## How It Works
 
-1. On `find()`, the SDK sends the current screenshot and cache metadata to the API
-2. The API compares the screenshot against previously cached results for the same `cacheKey`
-3. If the screen pixel diff is within the `screen` threshold AND the element template match exceeds the `element` threshold, the cached position is returned
-4. Otherwise, a new AI call is made and the result is cached
+1. On `find()`, the SDK sends the present screenshot and the cache metadata to the API.
+2. The API compares the screenshot against the cached results for the same `cacheKey`.
+3. If the screen pixel diff is in the `screen` threshold AND the element template match is more than the `element` threshold, TestDriver returns the cached position.
+4. If not, TestDriver makes a new AI call and caches the result.
 
 ```mermaid
 flowchart LR

package/ai/skills/testdriver-caching/SKILL.md

@@ -4,9 +4,10 @@ description: How TestDriver learns your app and caches what it discovers for ins
 ---
 <!-- Generated from caching.mdx. DO NOT EDIT. -->
 
-Once the agent has [explored your app](/generating-tests), TestDriver remembers what it found. Every element the AI vision agent discovers is cached with a vision fingerprint—a perceptual hash of the screen state where it was located. On the next run, TestDriver matches against that cache instead of calling the AI again. Passing tests replay instantly, deterministically, and cheaply.
+After the agent [explored your app](/generating-tests), TestDriver keeps what it found. TestDriver caches each element that the AI vision agent finds. It uses a vision fingerprint. This is a perceptual hash of the screen state at the element location. On the next run, TestDriver matches against that cache. It does not call the AI again. Tests that pass replay quickly, in the same way each time, and at a low cost.
+
+This learning makes TestDriver fast. The cache makes the test run a maximum of **1.7x faster**. It does not do the same AI vision analysis again. The agent thinks only when it sees something new.
 
-This learning is what makes TestDriver fast. Intelligent caching delivers up to **1.7x faster** test execution by skipping redundant AI vision analysis—the agent only thinks when it sees something new.
 
 ```javascript
 // First run: builds cache
@@ -18,14 +19,14 @@ await testdriver.find('submit button');
 
 ## Automatic Caching
 
-Learning is enabled automatically with zero configuration. The cache key—the fingerprint TestDriver uses to recognize what it already knows—is computed from:
+TestDriver enables learning automatically. You do not need configuration. TestDriver computes the cache key from these. The cache key is the fingerprint that TestDriver uses to know what it learned:
 
-- **File hash**: SHA-256 hash of the test file contents
-- **Selector prompt**: The exact text description passed to `find()`
-- **Screenshot context**: Perceptual hash of the current screen state
-- **Platform**: Operating system and browser version
+- **File hash**: The SHA-256 hash of the test file contents
+- **Selector prompt**: The exact text description that you give to `find()`
+- **Screenshot context**: The perceptual hash of the present screen state
+- **Platform**: The operating system and the browser version
 
-When you modify your test file, the hash changes automatically, invalidating stale cache entries and ensuring fresh AI analysis with your updated test logic.
+When you change your test file, the hash changes automatically. This makes the old cache entries not valid. Then TestDriver does a new AI analysis with your new test logic.
 
 ```javascript
 import { test } from 'vitest';
@@ -46,7 +47,7 @@ test('auto-cached test', async (context) => {
 
 ## Managing the Cache
 
-You can clear the cache within the TestDriver console. There, you'll also find previews of cached elements, the input prompts, as well as analytics on cache hit rates.
+You can clear the cache in the TestDriver console. There, you also find previews of cached elements, the input prompts, and analytics on the cache hit rates.
 
 <Card href="https://console.testdriver.ai/cache" title="TestDriver Cache" icon="database">
   Manage and clear your test cache from the TestDriver console.

package/ai/skills/testdriver-captcha/SKILL.md

@@ -6,7 +6,7 @@ description: Solve captchas using 2captcha service
 
 # Captcha Solving
 
-TestDriver can automatically solve captchas during your tests using the 2captcha service. This feature works on both **Linux** and **Windows** sandboxes.
+TestDriver can solve captchas automatically during your tests. It uses the 2captcha service. This feature works on **Linux** sandboxes and **Windows** sandboxes.
 
 ## Quick Start
 
@@ -20,12 +20,12 @@ console.log(result.success); // true
 console.log(result.token);   // The solved captcha token
 ```
 
-That's it! TestDriver will automatically:
-- Detect the captcha type on the page
-- Extract the sitekey
-- Solve the captcha via 2captcha
-- Inject the token into the page
-- Trigger any callbacks
+That is all. TestDriver does these automatically:
+- Finds the captcha type on the page
+- Gets the sitekey
+- Solves the captcha with 2captcha
+- Puts the token into the page
+- Starts the callbacks
 
 ## Supported Captcha Types
 

package/ai/skills/testdriver-ci-cd/SKILL.md

@@ -4,21 +4,21 @@ description: Run TestDriver tests in CI/CD with parallel execution and cross-pla
 ---
 <!-- Generated from ci-cd.mdx. DO NOT EDIT. -->
 
-TestDriver integrates seamlessly with popular CI providers, enabling automated end-to-end testing on every push and pull request.
+TestDriver integrates with the common CI providers. It lets you do automated end-to-end tests on each push and pull request.
 
 ## Authentication
 
-On **GitHub Actions, prefer OIDC** via the published `testdriverai/action` —
-there's no `TD_API_KEY` secret to store, copy, or rotate. The action proves the
-workflow is running inside your org and TestDriver exchanges that proof for your
+On **GitHub Actions, use OIDC** through the published `testdriverai/action`. Then
+there is no `TD_API_KEY` secret to store, copy, or change. The action shows that the
+workflow runs in your org. TestDriver changes that proof for your
 team's key at run time. See the GitHub Actions tab below.
 
-For other CI providers (or self-hosted runners without OIDC), fall back to a
-stored API key from [console.testdriver.ai/settings](https://console.testdriver.ai/settings),
-added as a `TD_API_KEY` secret in your CI provider's settings.
+For other CI providers (or self-hosted runners without OIDC), use a
+stored API key from [console.testdriver.ai/settings](https://console.testdriver.ai/settings).
+Add it as a `TD_API_KEY` secret in the settings of your CI provider.
 
 <Note>
-  Never commit your API key directly in code. Always use OIDC or your CI provider's secrets management.
+  Never commit your API key in the code. Always use OIDC or the secrets management of your CI provider.
 </Note>
 
 ## CI Provider Examples
@@ -27,10 +27,10 @@ added as a `TD_API_KEY` secret in your CI provider's settings.
   <Tab title="GitHub Actions">
     ### Authenticate with OIDC via `testdriverai/action` (recommended)
 
-    Use the published [`testdriverai/action`](https://github.com/testdriverai/action) — it mints the OIDC token, exchanges it for your team's API key, and exports `TD_API_KEY` for the steps that follow. **No `TD_API_KEY` secret to store or rotate.**
+    Use the published [`testdriverai/action`](https://github.com/testdriverai/action). It makes the OIDC token, changes it for your team's API key, and exports `TD_API_KEY` for the steps that come after. **There is no `TD_API_KEY` secret to store or change.**
 
     <Note>
-      One-time setup: authorize the [TestDriver GitHub App](https://console.testdriver.ai) for your org so the org → team binding exists. If your org authorized the App before OIDC support shipped, re-authorize once. If the App isn't authorized, the action fails with a console link (or falls back to the `api-key` secret if you provide one).
+      Do this one time: authorize the [TestDriver GitHub App](https://console.testdriver.ai) for your org. Then the org → team binding exists. If your org authorized the App before OIDC support was available, authorize it again one time. If the App is not authorized, the action fails with a console link. (Or it uses the `api-key` secret if you give one.)
     </Note>
 
     ```yaml .github/workflows/testdriver.yml

package/ai/skills/testdriver-claude-mcp-plugin/SKILL.md

@@ -67,6 +67,43 @@ This is the same config the plugin wires up for you — the plugin just bundles
 
 ---
 
+## Remote (hosted URL) install — no CLI, browser login
+
+TestDriver also runs a **hosted MCP server** you can connect to with just a URL. There is no `npx` command and no API key to paste: the server speaks OAuth 2.1, so your client opens a browser, you sign in with TestDriver, and the tools appear. It exposes the **full live tool set** (`session_start`, `find`, `click`, `type`, `assert`, …) plus the read-only data tools, all scoped to your team.
+
+Hosted endpoint:
+
+```text
+https://mcp.testdriver.ai/mcp
+```
+
+The server advertises its authorization server (Auth0) via [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) protected-resource metadata at:
+
+```text
+https://mcp.testdriver.ai/.well-known/oauth-protected-resource
+```
+
+Spec-compliant clients discover and complete the OAuth flow automatically:
+
+- **Claude** — add a custom connector pointing at the URL above; Claude runs the browser login for you.
+- **VS Code / Copilot** — add a remote MCP server entry with the URL; VS Code handles the OAuth handshake.
+- **ChatGPT** — add it as a connector by URL.
+- **Any spec-compliant client** — point it at the URL; it will read the metadata, sign you in, and connect.
+
+```json
+{
+  "mcpServers": {
+    "testdriver": {
+      "url": "https://mcp.testdriver.ai/mcp"
+    }
+  }
+}
+```
+
+Each connection gets its own isolated sandbox, so multiple people (or multiple chats) can run tests at the same time without interfering. The API-key paths above still work for automation and CI.
+
+---
+
 ## Observing test runs via HTTP MCP
 
 TestDriver also exposes **test results and analytics** over an HTTP MCP endpoint, so Claude Code (or any MCP-compatible client) can inspect your test runs, failures, and filters without provisioning a sandbox.

package/ai/skills/testdriver-client/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: testdriver:client
-description: Initialize and configure the TestDriver SDK client
+description: Create the TestDriver client, authenticate, and connect to a sandbox
 ---
 <!-- Generated from client.mdx. DO NOT EDIT. -->
 
 ## Overview
 
-The `TestDriver` client is the main entry point for the SDK. It handles authentication, sandbox connection, and provides access to all testing methods.
+The `TestDriver` client is the main entry point for the SDK. It does the authentication and the sandbox connection. It gives access to all test methods.
 
 ## Constructor
 
@@ -21,170 +21,7 @@ const testdriver = new TestDriver(apiKey, options)
 </ParamField>
 
 <ParamField path="options" type="object">
-  Configuration options for the client
-  
-  <Expandable title="properties">
-    <ParamField path="os" type="string" default="linux">
-      Operating system for the sandbox: `'windows'` or `'linux'`
-    </ParamField>
-    
-    <ParamField path="resolution" type="string" default="1366x768">
-      Screen resolution for the sandbox (e.g., `'1920x1080'`, `'1366x768'`). Custom resolutions are only available on Enterprise plans.
-    </ParamField>
-    
-    <ParamField path="apiRoot" type="string">
-      API endpoint URL (typically only changed for self-hosted deployments)
-    </ParamField>
-    
-    <ParamField path="analytics" type="boolean" default="true">
-      Enable or disable usage analytics
-    </ParamField>
-    
-    <ParamField path="logging" type="boolean" default="true">
-      Enable or disable console logging
-    </ParamField>
-    
-    <ParamField path="autoScreenshots" type="boolean" default="false">
-      Automatically capture screenshots before and after each command. Screenshots are saved to `.testdriver/screenshots/<test>/` with descriptive filenames that include the line number and action name. Format: `<seq>-<action>-<phase>-L<line>-<description>.png`
-    </ParamField>
-    
-    <ParamField path="newSandbox" type="boolean" default="true">
-      Force creation of a new sandbox instead of reusing an existing one
-    </ParamField>
-    
-    <ParamField path="reconnect" type="boolean" default="false">
-      Reattach to the last used sandbox instead of creating a new one. When `true`, the SDK reads the sandbox id from `.testdriver/last-sandbox` (written automatically on every successful connect) and rejoins that VM. Provision methods (`chrome`, `vscode`, `installer`, etc.) are skipped because the application is already running. The previous sandbox must still be alive — see [`keepAlive`](#keepalive) and the [Run guide](/copilot/running-tests#keeping-machines-alive-between-runs).
-    </ParamField>
-
-    <ParamField path="sandboxId" type="string">
-      Reattach to a specific sandbox id instead of the one recorded in `.testdriver/last-sandbox`. Use this for CI matrices or to pin a chain of tests to a known VM. Implies `reconnect: true` behavior (provision calls are skipped).
-    </ParamField>
-    
-    <ParamField path="preview" type="string" default="browser">
-      Preview mode for live test visualization:
-      - `"browser"` — Opens debugger in default browser (default)
-      - `"ide"` — Opens preview in IDE panel (VSCode, Cursor - requires TestDriver extension)
-      - `"none"` — Headless mode, no visual preview
-    </ParamField>
-    
-    <ParamField path="headless" type="boolean" default="false">
-      **Deprecated**: Use `preview: "none"` instead. Run in headless mode without opening the debugger.
-    </ParamField>
-    
-    <ParamField path="debugOnFailure" type="boolean" default="false">
-      Keep the sandbox alive when a test fails so you can reconnect and debug interactively. The sandbox ID is printed to the console.
-    </ParamField>
-    
-    <ParamField path="ip" type="string">
-      Direct IP address to connect to a running sandbox instance (for self-hosted deployments)
-    </ParamField>
-    
-    <ParamField path="sandboxAmi" type="string">
-      Custom AMI ID for the sandbox instance (AWS deployments, e.g., `'ami-1234'`)
-    </ParamField>
-    
-    <ParamField path="sandboxInstance" type="string">
-      EC2 instance type for the sandbox (AWS deployments, e.g., `'i3.metal'`)
-    </ParamField>
-    
-    <ParamField path="cache" type="boolean | object" default="true">
-      Enable or disable element caching, or provide advanced threshold configuration.
-      
-      <Expandable title="advanced config">
-        <ParamField path="enabled" type="boolean" default="true">
-          Enable or disable caching
-        </ParamField>
-        
-        <ParamField path="thresholds" type="object">
-          Fine-tune cache matching
-          
-          <Expandable title="properties">
-            <ParamField path="find" type="object">
-              Thresholds for `find()` operations
-              
-              <Expandable title="properties">
-                <ParamField path="screen" type="number" default="0.05">
-                  Pixel diff threshold for screen comparison (0-1). `0.05` = 5% diff allowed.
-                </ParamField>
-                
-                <ParamField path="element" type="number" default="0.8">
-                  OpenCV template match threshold for element matching (0-1). `0.8` = 80% correlation.
-                </ParamField>
-              </Expandable>
-            </ParamField>
-            
-            <ParamField path="assert" type="number" default="0.05">
-              Pixel diff threshold for `assert()` operations (0-1). `0.05` = 5% diff allowed.
-            </ParamField>
-          </Expandable>
-        </ParamField>
-      </Expandable>
-    </ParamField>
-    
-    <ParamField path="cacheKey" type="string">
-      Cache key for element finding operations. If provided, enables caching tied to this key.
-    </ParamField>
-    
-    <ParamField path="verify" type="boolean" default="false">
-      Global default for AI verification of located elements. When `true`, every `find()` runs a second AI check to confirm the returned coordinates actually match the requested element (catching hallucinated or incorrect positions), at the cost of extra latency. Can be overridden per call via `find(description, { verify: true | false })`.
-    </ParamField>
-    
-    <ParamField path="dashcam" type="boolean" default="true">
-      Enable or disable Dashcam video recording
-    </ParamField>
-    
-    <ParamField path="redraw" type="boolean | object" default="true">
-      Enable or disable screen-change (redraw) detection, or provide advanced configuration.
-      
-      <Expandable title="advanced config">
-        <ParamField path="enabled" type="boolean" default="true">
-          Enable or disable redraw detection
-        </ParamField>
-        
-        <ParamField path="thresholds" type="object">
-          Threshold configuration
-          
-          <Expandable title="properties">
-            <ParamField path="screen" type="number | false" default="0.05">
-              Pixel diff threshold (0-1). Set to `false` to disable screen redraw detection.
-            </ParamField>
-            
-            <ParamField path="network" type="boolean" default="false">
-              Enable or disable network activity monitoring
-            </ParamField>
-          </Expandable>
-        </ParamField>
-      </Expandable>
-    </ParamField>
-    
-    <ParamField path="environment" type="object">
-      Additional environment variables to pass to the sandbox
-    </ParamField>
-    
-    <ParamField path="ai" type="object">
-      Global AI sampling configuration. Controls how the AI model generates responses for `find()` verification and `assert()` calls. Can be overridden per call.
-      
-      <Expandable title="properties">
-        <ParamField path="temperature" type="number">
-          Controls randomness in AI responses. `0` = deterministic (best for verification), higher values = more creative. Default: `0` for find verification, model default for assert.
-        </ParamField>
-        
-        <ParamField path="top" type="object">
-          Nucleus and top-k sampling parameters
-          
-          <Expandable title="properties">
-            <ParamField path="p" type="number">
-              Top-P (nucleus sampling). Limits token choices to the smallest set whose cumulative probability exceeds P. Lower values = more focused responses. Range: 0-1.
-            </ParamField>
-            
-            <ParamField path="k" type="number">
-              Top-K sampling. Limits token choices to the top K most likely tokens. `1` = always pick the most likely token. `0` = disabled (consider all tokens).
-            </ParamField>
-          </Expandable>
-        </ParamField>
-      </Expandable>
-    </ParamField>
-  </Expandable>
+  The configuration options for the client. See [SDK Options](/options) for the full list, with defaults and examples for each option.
 </ParamField>
 
 ### Example

package/ai/skills/testdriver-customizing-devices/SKILL.md

@@ -6,7 +6,7 @@ description: Configure TestDriver sandbox options and environment settings
 
 ## TestDriver Options
 
-Configure TestDriver behavior with options passed to the `TestDriver()` function:
+Configure the TestDriver behavior with options that you give to the `TestDriver()` function:
 
 ```javascript
 const testdriver = TestDriver(context, {

package/ai/skills/testdriver-dashcam/SKILL.md

@@ -6,13 +6,13 @@ description: Record test execution with video and logs
 
 ## Overview
 
-Dashcam provides automatic video recording and log aggregation for your tests. It captures screen recordings, application logs, and test execution details that can be reviewed later.
+Dashcam makes automatic video recordings. It also collects the logs for your tests. It captures screen recordings, application logs, and test details. You can review them later.
 
 ## Basic Usage
 
 ### With Presets
 
-Most presets automatically include Dashcam:
+Most presets include Dashcam automatically:
 
 ```javascript
 import { test } from 'vitest';
@@ -33,7 +33,7 @@ test('my test', async (context) => {
 
 ### Manual Setup
 
-For more control, create a Dashcam instance directly:
+For more control, make a Dashcam instance directly:
 
 ```javascript
 import TestDriver from 'testdriverai';

package/ai/skills/testdriver-debugging-with-screenshots/SKILL.md

@@ -6,10 +6,10 @@ description: Diagnose failing tests with screenshots, replays, and logs
 
 ## Overview
 
-When a test fails, debug it by seeing exactly what happened — don't guess. TestDriver captures screenshots, video replays, and logs as your test runs, so you can replay the moment of failure instead of squinting at a stack trace. TestDriver MCP provides powerful commands to view and analyze the screenshots saved during test execution, enabling rapid debugging, test development, and comparison workflows without manually opening image files.
+When a test fails, debug it. Look at what happened. Do not guess. TestDriver captures screenshots, video replays, and logs while your test runs. Thus you can replay the moment of the failure. You do not need to look at a stack trace. TestDriver MCP gives commands to view and examine the screenshots that TestDriver saved during the test. This lets you debug quickly, develop tests, and compare, without a manual open of image files.
 
 <Note>
-  **Automatic Screenshots (Default: Enabled)**: TestDriver automatically captures screenshots before and after every command. Screenshots are named with the line number and action, making it easy to trace exactly which line of code produced each screenshot. For example: `001-click-before-L42-submit-button.png`
+  **Automatic Screenshots (Default: Enabled)**: TestDriver captures screenshots automatically before and after each command. The screenshot name has the line number and the action. Thus it is easy to see which line of code made each screenshot. For example: `001-click-before-L42-submit-button.png`
 </Note>
 
 ## MCP Commands
@@ -25,15 +25,15 @@ list_local_screenshots()
 **Filter Parameters:**
 
 <ParamField path="directory" type="string" optional>
-  Filter screenshots by test file or subdirectory (e.g., "login.test", "mcp-screenshots"). If omitted, lists all screenshots.
+  Filter the screenshots by test file or subdirectory (for example, "login.test", "mcp-screenshots"). If you do not give this, the tool lists all screenshots.
 </ParamField>
 
 <ParamField path="line" type="number" optional>
-  Filter by exact line number from test file (e.g., 42 matches L42 in filename).
+  Filter by the exact line number from the test file (for example, 42 matches L42 in the filename).
 </ParamField>
 
 <ParamField path="lineRange" type="object" optional>
-  Filter by line number range. Example: `{ start: 10, end: 20 }` matches screenshots from lines 10-20.
+  Filter by a line number range. Example: `{ start: 10, end: 20 }` matches screenshots from lines 10-20.
 </ParamField>
 
 <ParamField path="action" type="string" optional>

package/ai/skills/testdriver-elements/SKILL.md

@@ -6,22 +6,22 @@ description: Locate and interact with UI elements using AI
 
 ## Overview
 
-TestDriver's element finding system uses AI to locate elements on screen using natural language descriptions. The `find()` method returns an `Element` object that you can interact with.
+The TestDriver element finding system uses AI. It finds elements on the screen with natural language descriptions. The `find()` method returns an `Element` object. You can interact with the object.
 
 ## Finding Elements
 
 ### find()
 
-Locate an element on screen using a natural language description.
+Find an element on the screen with a natural language description.
 
 ```javascript
 const element = await testdriver.find(description)
 ```
 
 **Parameters:**
-- `description` (string) - Natural language description of the element to find
+- `description` (string) - A natural language description of the element to find
 
-**Returns:** `Promise<Element>` - Element instance that has been located
+**Returns:** `Promise<Element>` - The Element instance that TestDriver found
 
 **Example:**
 ```javascript
@@ -36,7 +36,7 @@ const redButton = await testdriver.find('red button in the top right corner');
 ```
 
 <Tip>
-  Be specific in your descriptions. Include visual details, location context, or nearby text to improve accuracy.
+  Be specific in your descriptions. Include visual details, location context, or nearby text to make the accuracy better.
 </Tip>
 
 ## Element Class

package/ai/skills/testdriver-errors/SKILL.md

@@ -6,7 +6,7 @@ description: Custom error classes and error handling
 
 ## Overview
 
-TestDriver provides custom error classes with rich debugging information. These are exported from the SDK and can be used for `instanceof` checks in your tests.
+TestDriver gives custom error classes with full debug information. The SDK exports them. You can use them for `instanceof` checks in your tests.
 
 ```javascript
 import TestDriver, { ElementNotFoundError, AIError } from 'testdriverai';
@@ -14,7 +14,7 @@ import TestDriver, { ElementNotFoundError, AIError } from 'testdriverai';
 
 ## ElementNotFoundError
 
-Thrown when `find()` cannot locate an element on screen, or when calling `click()`/`hover()` on an unfound element.
+TestDriver throws this when `find()` cannot find an element on the screen. It also throws this when you call `click()` or `hover()` on an element that TestDriver did not find.
 
 ```javascript
 try {
@@ -35,7 +35,7 @@ try {
 </ParamField>
 
 <ParamField path="message" type="string">
-  Enhanced message with a debug block containing element description, cache status, similarity scores, and AI response details.
+  A message with a debug block. The block has the element description, the cache status, the similarity scores, and the AI response details.
 </ParamField>
 
 <ParamField path="description" type="string">

package/ai/skills/testdriver-events/SKILL.md

@@ -6,9 +6,9 @@ description: Listen to SDK lifecycle events with wildcard support
 
 ## Overview
 
-TestDriver uses [EventEmitter2](https://github.com/EventEmitter2/EventEmitter2) for its event system. Events use a colon-delimited namespace pattern and support wildcard listeners.
+TestDriver uses [EventEmitter2](https://github.com/EventEmitter2/EventEmitter2) for its event system. Events use a namespace pattern with colons. They permit wildcard listeners.
 
-Access the emitter through `testdriver.emitter`:
+Use the emitter through `testdriver.emitter`:
 
 ```javascript
 testdriver.emitter.on('command:start', (data) => {
@@ -32,7 +32,7 @@ new EventEmitter2({
 
 ### Wildcard Listeners
 
-Use `*` to match a single level or `**` to match multiple levels:
+Use `*` to match one level. Use `**` to match many levels:
 
 ```javascript
 // Match all log events