@revyl/verify 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.3.2 (2026-11-11)
+
+- Fix `npx @revyl/verify init` in pnpm projects: it now runs `pnpm add -D`. pnpm 9 and 10 rejected `--dev`, and pnpm 12 read it as "install only devDependencies", saved Verify under `dependencies` without installing it, and removed the project's other dependencies from `node_modules`.
+- Fix `init` in Yarn projects: Yarn 3 and 4 get `--mode=skip-build` (the old `skip-builds` was rejected), Yarn 1 gets `--ignore-scripts`, and Yarn 2 gets a plain `add --dev`.
+- `init` passes your environment to the package manager, so Corepack, proxy, registry and npm configuration variables reach the install.
+- Add a `default` condition to the package exports of `@revyl/verify` and `revyl-verify`, so `verify.config.ts` loads in Yarn Plug'n'Play projects and CommonJS `require('@revyl/verify')` resolves through Node.js require(esm) on Node.js 22.12 and later.
+- The `verify` CLI exits with `Verify needs Node.js 22.18 or later` on older Node.js instead of running `init` and writing a script that Node cannot load.
+
+## Python 0.1.0 (2026-11-06)
+
+First PyPI release of `revyl-verify` (import `revyl_verify`, Python ≥3.10), published from the `py/v0.1.0` tag with PyPI trusted publishing and attestations.
+
+- Includes the Python surface described under 0.3.0 below: typed sync and asyncio sessions, `bundle_id` mobile targets, web and mobile instructions and validations, screenshots, encoded (`argv_b64`/`path_b64`) computer operations, hosted child sessions, `attach()` and `current_computer()`.
+- Sign in automatically on the first interactive `open()`, `attach()` or `current_computer()` call through the Revyl browser approval flow, saving the login to `~/.revyl/credentials.json` for the Revyl CLI and other SDKs. Non-interactive runs and `CI` stay key-only and never open a browser.
+- Verified live on production: the iOS Settings quickstart (`bundle_id="com.apple.Preferences"`) through a first-run browser sign-in, and a Mac `exec`/file round trip, from the built wheel in a clean virtual environment.
+
+## 0.3.1 (2026-11-03)
+
+- Docs: runnable `.mts` quickstart uses the built-in iOS Settings app, explains how to target an uploaded app with `appId`, clarifies that the Python SDK is not published to PyPI yet, and documents Web availability requirements.
+
 ## 0.3.0 (2026-10-31)
 
 - Sign in automatically on the first interactive `open()`, `attach()`, or `currentComputer()` call using the Revyl CLI browser-approval flow; CI remains key-only and browser-free.

package/README.md

@@ -1,21 +1,13 @@
 # Verify
 
-Verify runs end-to-end checks in a real browser, iOS simulator, or Android emulator on Revyl. You describe what the agent should do and what must be true afterward, instead of maintaining selectors and coordinates that break when a screen changes. Use it from a script, a coding agent, or the test runner you already have. Mac and Linux computers are also available for commands, files, and screenshots, not natural-language steps.
+![Terminal output from one Verify script beside a Mac computer's Terminal window showing the macOS version, and the screens the script reached in a cloud browser, an Android emulator, and an iOS simulator](https://raw.githubusercontent.com/RevylAI/verify/v0.3.2/docs/images/verify-hero.webp)
 
-Every run gives you a link to watch the target. The session keeps its report and available recording, and the SDK keeps instruction and validation results in order. A failed check leaves evidence you can inspect.
-
-## Install and run
-
-```bash
-npm install @revyl/verify
-```
-
-Save this as `verify/check.ts`:
+Verify runs end-to-end checks in a cloud browser, iOS simulator, or Android emulator on Revyl. You write what the agent should do and what must be true afterward, in plain sentences, and call it from a script, a coding agent, CI, or the test runner you already use. Verify also opens Mac and Linux computers for commands, files, and screenshots.
 
 ```ts
 import { open } from '@revyl/verify';
 
-const session = await open({ platform: 'ios', app: { appId: 'YOUR_REVYL_APP_ID' } });
+const session = await open({ platform: 'ios', app: { bundleId: 'com.apple.Preferences' } });
 try {
   await session.instruction('Open General, then About');
   await session.validation('The screen shows the operating system version');
@@ -25,117 +17,42 @@ try {
 }
 ```
 
-Run the script:
-
-```bash
-node verify/check.ts
-```
+You maintain sentences instead of selectors and coordinates that break when a screen changes, and every run prints a session link that keeps the report and available recording after the session closes.
 
-On the first interactive run, Verify opens the Revyl browser approval flow once and saves the login in `~/.revyl/credentials.json` for the CLI and SDK to share.
+## Quick start
 
-Verify prints a live session URL and progress like this:
+Paste this prompt into your coding agent, and it sets up Verify in the project's language:
 
 ```text
-[verify] ios: starting ios session https://app.revyl.ai/sessions/…
-[verify] ios: ready
-[verify] ios: ✓ instruction "Open General, then About" (12.0s)
-[verify] ios: ✓ validation "The screen shows the operating system version" (9.8s)
-[verify] ios: closed
-```
-
-The URL is live during the run and keeps the report and available recording after it closes. A failed instruction or validation throws a typed error and includes the same URL. In CI, Verify never opens a browser: provide `REVYL_API_KEY` as a secret.
-
-For Web, use `open({ platform: 'web', app: { appId, url } })`; for a computer, use `open({ platform: 'mac' })`.
-
-## Scaffold a config (optional)
+Set up Verify in this project.
 
-Use `init` when you want named targets in `verify.config.ts` and a generated `verify/example.ts` script:
+Read https://docs.revyl.com/verify.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl.
 
-```bash
-npx @revyl/verify init
-```
-
-`init` detects your package manager, asks before adding `@revyl/verify` as a dev dependency, creates `verify.config.ts` and `verify/example.ts`, and prints the command that runs the example. Use `--yes` to accept installation without a prompt, or `--no-install` when Verify is already installed. It is optional; installing the package is enough to use inline targets.
-
-The generated project starts with a named target. Use `--platform web`, `--platform ios`, `--platform android`, or `--platform mac` when you want to skip the platform question. Web and mobile targets need a Revyl app id; a Mac target does not. The generated config is ordinary TypeScript, so edit it when the example needs a pinned build, a public Web URL, or a different target.
-
-See the [TypeScript getting-started guide](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/getting-started.md), the [Python SDK guide](https://github.com/RevylAI/verify/blob/v0.3.0/python/README.md), and the [Go SDK guide](https://github.com/RevylAI/verify/tree/go/v0.2.0/go).
+Use the SDK for this project's language: @revyl/verify on Node.js 22.18 or later for Node.js or TypeScript, revyl-verify on Python 3.10 or later for Python (install it with pip or uv), or the github.com/RevylAI/verify/go module for Go. Write the iOS Settings example in that language: open the com.apple.Preferences bundle, run one instruction, and run one validation that checks the operating system version. Ask before starting a paid cloud session, then run the example.
 
-## CI
+You're done when the example has opened iOS Settings, the operating system version validation has passed, and the session has closed.
 
-For a normal GitHub Actions job, install from the lockfile with `npm ci` and pass `REVYL_API_KEY` from repository secrets to the script that runs Verify:
-
-```yaml
-- uses: actions/checkout@v5
-- uses: actions/setup-node@v5
-  with:
-    node-version: 24
-    cache: npm
-- run: npm ci
-- run: node verify/example.ts
-  env:
-    REVYL_API_KEY: ${{ secrets.REVYL_API_KEY }}
+Ask me before anything that needs my login or approval.
 ```
 
-On a `revyl-macos` job, `currentComputer()` attaches to the runner's existing computer without taking ownership. The runner releases the computer; closing the Verify attachment still cleans up hosted children. See the [CI guide](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/ci.md) and [computer API](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/api.md#inside-a-revyl-macos-github-actions-job).
-
-## Reference authentication
-
-Use manual setup when you need to control the package manager or keep the generated files out of the project:
+Or set it up yourself:
 
 ```bash
-revyl auth login
-npx @revyl/verify whoami
-```
-
-The SDK resolves credentials in this order: a usable stored CLI login marked `local_auth_override`, `REVYL_API_KEY`, then another usable stored CLI login. In CI, use a secret manager rather than putting a key in source, command arguments, or logs. `whoami` checks the credentials without starting a session.
-
-## TypeScript
-
-```ts
-import { open } from '@revyl/verify';
-
-const session = await open('ios');
-try {
-  await session.instruction('Open General, then About');
-  await session.validation('The screen shows the operating system version');
-} finally {
-  await session.close();
-}
-```
-
-For Web, use a public HTTPS URL in the target config. For iOS and Android, point the target at an app or build in Revyl. The [API guide](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/api.md) covers target options, step results, screenshots, reports, and cleanup.
-
-## Go
-
-Inside a function returning `error`, with a bounded `ctx`:
-
-```go
-session, err := verify.Open(ctx, verify.Target{Platform: verify.IOS, BundleID: "com.apple.Preferences"})
-if err != nil {
-    return err
-}
-defer func() { _ = session.Close(ctx) }()
-if _, err := session.Instruction(ctx, "Open General, then About"); err != nil {
-    return err
-}
-_, err = session.Validation(ctx, "The screen shows the operating system version")
-return err
+npx @revyl/verify init
 ```
 
-Go calls return errors instead of throwing. The [Go reference](https://github.com/RevylAI/verify/tree/go/v0.2.0/go) covers context deadlines, screenshots, computer operations, and hosted sessions.
+`init` adds Verify to your project, asks what to open, writes `verify.config.ts` and an example script, signs you in through the browser on the first interactive run, and prints the command that runs the example. To skip the config, run `npm install @revyl/verify` and save the example above as `verify/check.mts`, then run `node verify/check.mts`. [Getting started](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/getting-started.md) covers sign-in, your own app, and [CI](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/ci.md).
 
-## Python
+For finished projects, see [`examples/`](https://github.com/RevylAI/verify/tree/v0.3.2/examples/): a [web store](https://github.com/RevylAI/verify/tree/v0.3.2/examples/web-store/), [mobile Settings](https://github.com/RevylAI/verify/tree/v0.3.2/examples/mobile-settings/), a [Mac workspace](https://github.com/RevylAI/verify/tree/v0.3.2/examples/mac-workspace/), and a small [agent platform](https://github.com/RevylAI/verify/tree/v0.3.2/examples/agent-platform/) that runs web and iOS side by side.
 
-```python
-from revyl_verify import Target, open
+## Packages
 
-with open(Target(platform="ios", bundle_id="com.apple.Preferences")) as session:
-    session.instruction("Open General, then About")
-    session.validation("The screen shows the operating system version")
-```
-
-Python supports synchronous and asyncio APIs, but it has no bundled CLI. The [Python reference](https://github.com/RevylAI/verify/blob/v0.3.0/python/README.md) covers both APIs and computer operations.
+| Package | Install | Status |
+| --- | --- | --- |
+| [`@revyl/verify`](https://www.npmjs.com/package/@revyl/verify) | `npm install @revyl/verify` | TypeScript SDK and the `verify` CLI (`init`, `whoami`). Published on npm, Node.js 22.18 or later. |
+| [`revyl-verify`](https://www.npmjs.com/package/revyl-verify) (npm) | `npm install revyl-verify` | Alias of `@revyl/verify` at the same version. |
+| [Go module](https://github.com/RevylAI/verify/tree/go/v0.2.0/go) | `go get github.com/RevylAI/verify/go@v0.2.0` | Published as the `go/v0.2.0` tag, Go 1.26.9 or later. Calls return errors instead of throwing. |
+| [`revyl-verify`](https://pypi.org/project/revyl-verify/) (PyPI) | `pip install revyl-verify` or `uv add revyl-verify` | Python SDK, published on PyPI. Python 3.10 or later, sync and asyncio APIs, no CLI; see the [Python guide](https://github.com/RevylAI/verify/blob/v0.3.2/python/README.md). |
 
 ## Platforms
 
@@ -147,22 +64,24 @@ Python supports synchronous and asyncio APIs, but it has no bundled CLI. The [Py
 | Mac computer | — | Yes | Yes |
 | Linux computer | — | Yes | Yes |
 
-Computer targets are early access and use commands, files, processes, and screenshots rather than natural-language agent steps. They have a server-bounded lifetime. See [computer setup](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/computers.md).
+Web is available to every organization. Mac and Linux computers are early access and have a server-bounded lifetime; see [computers](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/computers.md).
 
 ## Documentation
 
-- [Documentation index](https://github.com/RevylAI/verify/tree/v0.3.0/packages/verify/docs/) · [API](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/api.md) · [CI](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/ci.md) · [Coding agents](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/agents.md)
-- [End-to-end results and limitations](https://github.com/RevylAI/verify/blob/v0.3.0/packages/verify/docs/end-to-end.md)
-- [Examples](https://github.com/RevylAI/verify/tree/v0.3.0/examples/): [Web store](https://github.com/RevylAI/verify/tree/v0.3.0/examples/web-store/) · [Mobile Settings](https://github.com/RevylAI/verify/tree/v0.3.0/examples/mobile-settings/) · [Mac workspace](https://github.com/RevylAI/verify/tree/v0.3.0/examples/mac-workspace/)
-- [Contributing](https://github.com/RevylAI/verify/blob/v0.3.0/CONTRIBUTING.md) · [Security](https://github.com/RevylAI/verify/blob/v0.3.0/SECURITY.md) · [Releasing](https://github.com/RevylAI/verify/blob/v0.3.0/RELEASING.md)
+The [documentation](https://github.com/RevylAI/verify/tree/v0.3.2/packages/verify/docs/) covers the [API](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/api.md), [configuration](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/configuration.md), [web](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/web.md), [mobile](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/mobile.md), [computers](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/computers.md), [CI](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/ci.md), [errors and troubleshooting](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/errors.md), [coding agents](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/agents.md), and [live end-to-end results](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/end-to-end.md). The npm package ships these pages in `node_modules/@revyl/verify/docs/`, with an [llms.txt](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/llms.txt) index, so a coding agent can read the docs for the version you installed. The Revyl docs site has an overview at [docs.revyl.com/verify](https://docs.revyl.com/verify).
+
+## Security
+
+Don't open a public issue for a vulnerability. Follow [SECURITY.md](https://github.com/RevylAI/verify/blob/v0.3.2/SECURITY.md) and email support@revyl.ai. Each session is a paid remote session that acts on your app, and step text is sent to Revyl and printed to stderr, so use test accounts and keep credentials and customer data out of steps.
+
+## Telemetry
+
+Verify sends no usage telemetry of its own. Its requests to the Revyl API carry a `User-Agent` with the Verify and runtime versions and an `X-Revyl-Client: verify` header.
 
-## Troubleshooting
+## Status
 
-- **`NOT_AVAILABLE_ON_PLATFORM`:** the requested method is not available for that target. Computer targets do not run instruction or validation steps; Web and mobile targets do not expose computer commands or files.
-- **`COMPUTER_LIMIT`:** computer admission was refused because of queued work or a concurrency limit. Verify does not retry creation or stop a definitely refused start.
-- **Blank first screen:** mobile startup uses a bounded, best-effort blank-frame observation, not a rendered-readiness guarantee. Begin with an instruction that reaches the screen your workflow needs.
-- **A validation report looks successful but the assertion failed:** inspect each step's `effective_status` and `validation_result`, and compare `validations_passed` with `total_validations` rather than transport counters.
+Verify is at 0.x, so APIs can still change between minor releases; the [changelog](https://github.com/RevylAI/verify/blob/v0.3.2/CHANGELOG.md) records each release. Mac and Linux computers are early access. See [Contributing](https://github.com/RevylAI/verify/blob/v0.3.2/CONTRIBUTING.md) and [Releasing](https://github.com/RevylAI/verify/blob/v0.3.2/RELEASING.md) to work on Verify.
 
 ## License
 
-[Apache 2.0](https://github.com/RevylAI/verify/blob/v0.3.0/LICENSE).
+[Apache 2.0](https://github.com/RevylAI/verify/blob/v0.3.2/LICENSE).

package/dist/cli/install.js

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { VerifyError } from '../errors.js';
 import { PACKAGE_NAME } from '../version.js';
@@ -32,24 +32,29 @@ export async function installVerify(cwd) {
     const manager = detectPackageManager(cwd);
     if (!existsSync(join(cwd, 'package.json')))
         await writeFile(join(cwd, 'package.json'), '{\n  "private": true,\n  "type": "module"\n}\n', { flag: 'wx' });
+    const shell = process.platform === 'win32';
     const args = manager === 'npm'
         ? ['install', '--save-dev', '--ignore-scripts']
-        : manager === 'yarn'
-            ? ['add', '--dev', '--mode=skip-builds']
-            : ['add', '--dev', '--ignore-scripts'];
+        : manager === 'pnpm'
+            ? ['add', '-D', '--ignore-scripts']
+            : manager === 'yarn'
+                ? yarnAddArgs(cwd, shell)
+                : ['add', '--dev', '--ignore-scripts'];
     args.push(PACKAGE_NAME);
     process.stdout.write(`Installing ${PACKAGE_NAME} with ${manager}...\n`);
     await new Promise((resolve, reject) => {
-        const env = Object.fromEntries(['PATH', 'HOME', 'USERPROFILE', 'TMPDIR', 'TEMP', 'TMP'].flatMap((key) => {
-            const value = process.env[key];
-            return value === undefined ? [] : [[key, value]];
-        }));
-        const child = spawn(manager, args, { cwd, env, stdio: 'inherit', shell: process.platform === 'win32', timeout: 180_000, killSignal: 'SIGKILL' });
+        const child = spawn(manager, args, { cwd, stdio: 'inherit', shell, timeout: 180_000, killSignal: 'SIGKILL' });
         const fail = () => reject(new VerifyError('CONFIG_INVALID', `Could not install ${PACKAGE_NAME} with ${manager}. Install it manually, then retry init --no-install.`));
         child.once('error', fail);
         child.once('exit', (code) => code === 0 ? resolve() : fail());
     });
 }
+function yarnAddArgs(cwd, shell) {
+    const major = Number.parseInt(spawnSync('yarn', ['--version'], { cwd, shell, encoding: 'utf8', timeout: 60_000 }).stdout?.trim() ?? '', 10);
+    if (major === 1)
+        return ['add', '--dev', '--ignore-scripts'];
+    return major >= 3 ? ['add', '--dev', '--mode=skip-build'] : ['add', '--dev'];
+}
 function detectPackageManager(cwd) {
     const lockfiles = [['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'], ['bun.lock', 'bun'], ['bun.lockb', 'bun'], ['package-lock.json', 'npm'], ['npm-shrinkwrap.json', 'npm']];
     for (let directory = cwd;; directory = dirname(directory)) {

package/dist/cli/main.js

@@ -142,6 +142,11 @@ async function whoamiCommand() {
     return 0;
 }
 export async function runCli(argv) {
+    const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
+    if (major < 22 || (major === 22 && minor < 18)) {
+        process.stderr.write(`Verify needs Node.js 22.18 or later; this is Node.js ${process.version}.\n`);
+        return 1;
+    }
     try {
         return await main(argv);
     }

package/docs/README.md

@@ -12,7 +12,7 @@ These files ship inside the npm package at `node_modules/@revyl/verify/docs/`, s
 | [mobile.md](mobile.md) | Open an iOS or Android app on a Revyl cloud device |
 | [computers.md](computers.md) | Open a Mac or Linux computer for commands, files, processes, screenshots, and optional recording metadata |
 | [ci.md](ci.md) | Call Verify from CI or from a test runner you already use |
-| [errors.md](errors.md) | Understand an error code and fix it |
+| [errors.md](errors.md) | Understand an error code and fix it, or troubleshoot a common problem |
 | [agents.md](agents.md) | Use Verify as a coding agent |
 
 [llms.txt](llms.txt) lists the same files in the llms.txt format.

package/docs/api.md

@@ -29,7 +29,7 @@ const linux = await open({ platform: 'linux' });                    // same comp
 
 `currentComputer(options?)` attaches to `REVYL_COMPUTER_ID` using normal credential resolution. It is non-owning by default: close cleans up hosted children, while the job's owner releases the computer. It never creates a computer and throws `COMPUTER_ID_MISSING` when the ID is unset or blank. Invalid IDs fail with `INVALID_ARGUMENT`.
 
-This helper is included in the TypeScript 0.3.0 release and requires a runner configured to inject `REVYL_COMPUTER_ID` and a short-lived `REVYL_API_KEY`. A workflow can supply its own `REVYL_API_KEY` instead. After installing the project dependencies and selecting Node.js ≥22.18, add this step to a job with `runs-on: revyl-macos`:
+This helper is included in the TypeScript 0.3.1 release and requires a runner configured to inject `REVYL_COMPUTER_ID` and a short-lived `REVYL_API_KEY`. A workflow can supply its own `REVYL_API_KEY` instead. After installing the project dependencies and selecting Node.js ≥22.18, add this step to a job with `runs-on: revyl-macos`:
 
 ```yaml
 - name: Run Verify
@@ -49,7 +49,7 @@ The helper accepts the same options as `attach`, including explicit `backendUrl`
 
 ## attach(computerId, options?)
 
-The attachment, hosted-child and navigation APIs below are included in the TypeScript 0.3.0 release.
+The attachment, hosted-child and navigation APIs below are included in the TypeScript 0.3.1 release.
 
 `open()` and `computer.open()` return the extended `OpenedSession` interface. The original `Session` interface keeps its existing required members, so applications implementing or mocking it do not need to add the new methods. Use `OpenedSession` when explicitly annotating a value that calls `report`, `navigate` or `open`.
 

package/docs/ci.md

@@ -38,6 +38,10 @@ To open each pull request's preview deployment on web, read the URL from the env
 web: { platform: 'web', app: { appId: process.env.REVYL_APP_ID!, url: process.env.PREVIEW_URL!, branch: process.env.GITHUB_HEAD_REF } }
 ```
 
+## On a revyl-macos runner
+
+On a `revyl-macos` job, `currentComputer()` attaches to the runner's existing computer without taking ownership. The runner releases the computer; closing the Verify attachment still cleans up hosted children. See [the computer API](api.md#inside-a-revyl-macos-github-actions-job) for the workflow step.
+
 ## Inside a test runner
 
 Verify has no test runner of its own. Call it from the one you already use, and close the session in `finally` or an `after` hook: test runners handle errors and shutdown themselves, so Verify's automatic cleanup steps aside for them.

package/docs/errors.md

@@ -62,3 +62,11 @@ try {
 `EDGE_BLOCKED` does not require Cloudflare branding in the HTML body. A `cf-ray` header alone is not proof of a block: any syntactically valid JSON body retains its existing error mapping, even if the content type is incorrectly `text/html`. HTTP 401 is unchanged. Edge-block errors include `httpStatus` but never copy the response body or ray ID into the error.
 
 Computer operations use `TIMEOUT` for bounded runtime with confirmed termination, and `ACTION_UNCERTAIN` when termination, execution, or cleanup is unconfirmed. An observed successful operation can return its result while logging pending/failed evidence. Timeout never proves rollback, and failed evidence does not prove the command never ran. Never automatically retry a mutation with a fresh request id; inspect the computer first. See [computers.md](computers.md).
+
+## Troubleshooting
+
+- **`NOT_AVAILABLE_ON_PLATFORM`:** the requested method is not available for that target. Computer targets do not run instruction or validation steps; Web and mobile targets do not expose computer commands or files.
+- **`COMPUTER_LIMIT`:** computer admission was refused because of queued work or a concurrency limit. Verify does not retry creation or stop a definitely refused start.
+- **Blank first screen:** mobile startup uses a bounded, best-effort blank-frame observation, not a rendered-readiness guarantee. Begin with an instruction that reaches the screen your workflow needs. See [mobile.md](mobile.md#steps).
+- **A validation report looks successful but the assertion failed:** inspect each step's `effective_status` and `validation_result`, and compare `validations_passed` with `total_validations` rather than transport counters. See [reading the verdict](end-to-end.md#reading-the-verdict).
+- **`Verify needs Node.js 22.18 or later`, or `ERR_UNKNOWN_FILE_EXTENSION` for a `.ts` or `.mts` script:** Verify needs Node.js 22.18 or later, which runs TypeScript files directly. Older versions refuse the script before Verify loads, and npm only warns (`EBADENGINE`) when you install on them. Check `node -v` and upgrade.

package/docs/getting-started.md

@@ -8,25 +8,45 @@ Verify needs Node.js 22.18 or later, which runs TypeScript files directly, and a
 npm install @revyl/verify
 ```
 
-Use an inline target when you do not need a named config:
+Save this as `verify/check.mts` and use an inline target when you do not need a named config:
 
 ```ts
 import { open } from '@revyl/verify';
 
-const session = await open({ platform: 'ios', app: { appId: 'YOUR_REVYL_APP_ID' } });
+const session = await open({ platform: 'ios', app: { bundleId: 'com.apple.Preferences' } });
 try {
-    await session.instruction('Open the main navigation');
-    await session.validation('The main navigation is visible');
+    await session.instruction('Open General, then About');
+    await session.validation('The screen shows the operating system version');
 } finally {
     await session.close();
 }
 ```
 
-On the first interactive run, Verify opens the Revyl browser approval flow once and saves the shared CLI login. It prints a live session link, then ordered step results. In CI, it never prompts or opens a browser; set `REVYL_API_KEY` as a secret. Python and Go use an existing CLI login or API key; their SDKs do not open the browser themselves.
+Use `appId` when you want to target your own uploaded app.
+
+Run it with `node verify/check.mts`. Web is available to every organization. If `revyl app create --platform web` reports `Web is not enabled for this organization`, Revyl has turned Web off for your organization; email support@revyl.ai. For a Web target, use `open({ platform: 'web', app: { appId, url } })`; for a computer, use `open({ platform: 'mac' })`.
+
+On the first interactive run, Verify opens the Revyl browser approval flow once and saves the login in `~/.revyl/credentials.json` for the CLI and SDK to share. It prints a live session link, then ordered step results:
+
+```text
+[verify] ios: starting ios session https://app.revyl.ai/sessions/…
+[verify] ios: ready
+[verify] ios: ✓ instruction "Open General, then About" (12.0s)
+[verify] ios: ✓ validation "The screen shows the operating system version" (9.8s)
+[verify] ios: closed
+```
+
+![Recording of the quickstart run at 4× speed: the terminal prints each step while the simulator opens General, then About](https://raw.githubusercontent.com/RevylAI/verify/9fd547fcef928cca990c1009f9e4284d6675437b/docs/images/verify-run.gif)
+
+The URL is live during the run and keeps the report and available recording after it closes. A failed instruction or validation throws a typed error and includes the same URL.
+
+![The Revyl session report for the run, showing the device recording, the Launch, Instruction, and Validation steps, and the validation's reasoning](https://raw.githubusercontent.com/RevylAI/verify/9fd547fcef928cca990c1009f9e4284d6675437b/docs/images/verify-session-report.webp)
+
+In CI, Verify never prompts or opens a browser; set `REVYL_API_KEY` as a secret. Python and Go use an existing CLI login or API key; their SDKs do not open the browser themselves.
 
 ## Scaffold a config (optional)
 
-Use `init` when you want named targets in `verify.config.ts` and a generated example script. It adds Verify with the package manager selected by its lockfile, asks what you want to open, and adds `.verify/` to `.gitignore`:
+Use `init` when you want named targets in `verify.config.ts` and a generated example script. It is optional; installing the package is enough to use inline targets. It detects your package manager from the lockfile, asks before adding `@revyl/verify` as a dev dependency, asks what you want to open, adds `.verify/` to `.gitignore`, and prints the command that runs the example:
 
 - `verify.config.ts`: the targets `open()` can start, by name
 - `verify/example.ts`: a script that opens the target, runs steps and takes a screenshot (web/mobile) or checks commands and files (Mac), and closes
@@ -39,11 +59,11 @@ npx @revyl/verify init --platform ios --app-id <revyl-app-id>
 npx @revyl/verify init --platform mac
 ```
 
-Use `--yes` to accept installation without a prompt, or `--no-install` when Verify is already installed.
+Use `--yes` to accept installation without a prompt, or `--no-install` when Verify is already installed. Web and mobile targets need a Revyl app id; a Mac target does not. The generated config is ordinary TypeScript, so edit it when the example needs a pinned build, a public Web URL, or a different target.
 
 ## Manual setup
 
-Verify uses the same credential precedence as the Revyl CLI:
+Use manual setup when you need to control the package manager or keep the generated files out of the project. Verify uses the same credential precedence as the Revyl CLI:
 
 1. A usable login in `~/.revyl/credentials.json` marked `local_auth_override` takes precedence, even when `REVYL_API_KEY` is set.
 2. Otherwise, `REVYL_API_KEY`, an API key you create in Revyl's settings.
@@ -54,6 +74,8 @@ export REVYL_API_KEY=...        # or: revyl auth login
 npx @revyl/verify whoami         # checks the credentials without starting a session
 ```
 
+In CI, keep the key in a secret manager rather than in source, command arguments, or logs.
+
 ## Point the config at your app
 
 Web and mobile targets need an app. Open the app in Revyl and copy its id into `app.appId`, or set `REVYL_APP_ID`, which the generated config reads. Mac and Linux targets need no app id. Linux init is intentionally unavailable; use `open({ platform: 'linux' })` or add a Linux config target.
@@ -68,7 +90,7 @@ Web and mobile targets need an app. Open the app in Revyl and copy its id into `
 node verify/example.ts
 ```
 
-If Node warns that the module type is not specified, add `"type": "module"` to your `package.json` or rename the script to `example.mts`.
+If Node warns that the module type is not specified, add `"type": "module"` to your `package.json` or rename the script to `example.mts`. In a Yarn Plug'n'Play project, the default since Yarn 2, run it with `yarn node verify/example.ts`.
 
 Illustrative output (durations vary):
 

package/docs/web.md

@@ -2,6 +2,8 @@
 
 A web target opens your app in a Revyl cloud browser.
 
+Web is available to every organization. If `revyl app create --platform web` reports `Web is not enabled for this organization`, Revyl has turned Web off for your organization; email support@revyl.ai.
+
 ```ts
 {
   platform: 'web',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revyl/verify",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Open Revyl cloud browsers and mobile devices for agent steps, or Mac and Linux computers for commands and files, from TypeScript.",
   "keywords": [
     "e2e",
@@ -32,7 +32,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./package.json": "./package.json"
   },