docs: clarify Playwright engine and runtime dependency models

cli/dependencies.mdx

@@ -1,43 +1,54 @@
 ---
-title: Using NPM packages and local dependencies
-sidebarTitle: NPM & Local Dependencies
+title: Using npm packages and local dependencies
+sidebarTitle: npm & Local Dependencies
 ---
 
-Checkly lets you use JavaScript / TypeScript in your [Browser](/detect/synthetic-monitoring/browser-checks/overview) and [Multistep](/detect/synthetic-monitoring/multistep-checks/overview) checks, [API check setup & teardown scripts](/detect/synthetic-monitoring/api-checks/setup-and-teardown), and [Playwright Check Suites](/detect/synthetic-monitoring/playwright-checks/overview). Checks are able to use NPM packages, as well as import local JavaScript and TypeScript files.
+Checkly lets you use JavaScript and TypeScript in your [Browser](/detect/synthetic-monitoring/browser-checks/overview) and [Multistep](/detect/synthetic-monitoring/multistep-checks/overview) checks, [API check setup and teardown scripts](/detect/synthetic-monitoring/api-checks/setup-and-teardown), and [Playwright Check Suites](/detect/synthetic-monitoring/playwright-checks/overview). Checks can use npm packages and import local JavaScript and TypeScript files.
 
-## NPM packages
+How dependencies work depends on the check type:
+
+| Check type | Dependency model | Environment field |
+|------------|------------------|-------------------|
+| Browser Checks and Multistep Checks | Run in a Checkly runtime with fixed Checkly-provided dependencies | `runtimeId` |
+| Playwright Check Suites | Install dependencies from your project files, including `package.json` and your lock file | `engine` |
+
+Use `runtimeId` to choose a custom Checkly runtime for Browser Checks and Multistep Checks. Use `engine` only for Playwright Check Suites, where it overrides the JavaScript engine version that runs your own Playwright project.
+
+## npm packages
 
 ### Browser, Multistep, and API Checks
 
-<Note>Not all NPM packages from NPM are available inside the context of a Check.</Note>
+<Note>Not all npm packages are available in a Checkly runtime.</Note>
 
 The JavaScript code for these check types executes in a runtime environment managed by Checkly.
 Runtime versions can be selected by setting a `runtimeId`.
-This can be configured at the check and group level using constructs, and a default value for the project can be set in the [project configuration file](/constructs/project#param-checks-runtime-id).
+You can configure `runtimeId` at the check and group level using constructs, and set a project default in the [project configuration file](/constructs/project#param-checks-runtime-id).
 
-A runtime contains among others:
+A runtime includes fixed dependencies such as:
 
-- Nodejs v22+
+- Node.js 22+
 - `@playwright/test 1.51.1`
 - `axios 0.28.0`
 - `lodash 4.17.21`
 - `moment 2.30.1`
 
-...and a range of other popular NPM package to help you write and assert checks.
+Runtimes also include other popular npm packages to help you write and assert checks.
 
 - [Browse the latest runtime specs](/platform/runtimes/runtime-specification)
 - [Learn more about runtimes](/platform/runtimes/overview)
-- [Why can't I import any NPM package or other 3rd party dependencies?](/platform/runtimes/overview#why-can’t-i-import-any-npm-package-or-other-3rd-party-dependencies%3F)
+- [Why can't I import any npm package or other third-party dependencies?](/platform/runtimes/overview)
 
 ### Playwright Check Suites
 
-Playwright Check Suites don't use our predefined runtimes. Instead, you can install [custom dependencies](/detect/synthetic-monitoring/playwright-checks/custom-dependencies/), including private packages or packages from a custom registry.
+Playwright Check Suites do not use Checkly runtimes. Instead, Checkly installs your project's dependencies from your `package.json` and lock file. This lets you use [custom dependencies](/detect/synthetic-monitoring/playwright-checks/custom-dependencies/), including private packages or packages from a custom registry.
+
+Use the `engine` field to override the JavaScript engine version for a Playwright Check Suite. `engine` does not select a Checkly runtime or a fixed package set.
 
 ## Local Dependencies
 
-Your checks are also able to import other JavaScript and TypeScript files as dependencies.
+Your checks can also import other JavaScript and TypeScript files as dependencies.
 This is useful for defining helper functions to be reused across multiple checks.
-The Checkly CLI will automatically detect these dependencies and make sure that they're bundled as part of the check.
+The Checkly CLI automatically detects these dependencies and bundles them with the check.
 No additional configuration is needed.
 
 Here is a [Browser Check](/detect/synthetic-monitoring/browser-checks/overview) example of how this works in practice.
@@ -86,8 +97,7 @@ import { BrowserCheck } from 'checkly/constructs'
 
 new BrowserCheck('login-check', {
   name: 'Login Check',
-    code: { entrypoint: './login.spec.ts' }
-  })
+  code: { entrypoint: './login.spec.ts' }
 })
 ```
 

constructs/browser-check.mdx

@@ -243,6 +243,26 @@ new BrowserCheck("standard-check", {
 **Available frequencies**: `EVERY_1M`, `EVERY_2M`, `EVERY_5M`, `EVERY_10M`, `EVERY_15M`, `EVERY_30M`, `EVERY_1H`, `EVERY_2H`, `EVERY_6H`, `EVERY_12H`, `EVERY_24H`
 </ResponseField>
 
+<ResponseField name="runtimeId" type="string">
+
+The Checkly runtime version used to execute the Browser Check. Runtimes are managed execution environments for Browser and Multistep Checks. They include fixed Checkly-provided dependencies, such as Playwright, browser binaries, and runtime libraries.
+
+Use `runtimeId` for Browser Checks and Multistep Checks. For Playwright Check Suites, use [`engine`](/constructs/playwright-check#engine) instead to select the JavaScript engine version that runs your own Playwright project.
+
+**Usage:**
+
+```ts highlight={3}
+new BrowserCheck("my-check", {
+  name: "My Browser Check",
+  runtimeId: "2025.04",
+  /* More options... */
+})
+```
+
+<Tip>Learn more about [Checkly runtimes in the general documentation](/platform/runtimes/overview).</Tip>
+
+</ResponseField>
+
 <ResponseField name="locations" type="string[]" default="[]">
 Array of public location codes where the Browser Check should run. Multiple locations provide geographic coverage and redundancy.
 

constructs/multistep-check.mdx

@@ -272,7 +272,9 @@ new MultiStepCheck("my-multistep", {
 </ResponseField>
 
 <ResponseField name="runtimeId" type="string">
-The ID of the runtime to use for executing the multistep check. Required to be `2023.09` or later for multistep check support.
+The Checkly runtime version used to execute the Multistep Check. Runtimes are managed execution environments for Browser and Multistep Checks. They include fixed Checkly-provided dependencies, such as Playwright, browser binaries, and runtime libraries.
+
+Multistep checks require runtime `2023.09` or later.
 
 Usage:
 ```ts highlight={3}

constructs/playwright-check.mdx

@@ -36,18 +36,18 @@ new PlaywrightCheck("critical-e2e-monitor", {
 ```
 
 ```ts Advanced Example
-import { PlaywrightCheck } from "checkly/constructs"
+import { Engine, PlaywrightCheck } from "checkly/constructs"
 
 new PlaywrightCheck("critical-e2e-monitor", {
   name: "Critical E2E Monitor",
   description: "Runs the **critical path** e2e suite against production.",
-  include: ['.npmrc','test-files/**'],
+  include: [".npmrc", "test-files/**"],
   playwrightConfigPath: "./playwright.config.ts",
+  engine: Engine.node("24"), // Optional: override the auto-detected engine.
   installCommand: "npm ci",
   testCommand: "npx playwright test --retries=2",
   pwProjects: ["chromium"],
   pwTags: ["e2e"],
-
 })
 ```
 
@@ -68,6 +68,7 @@ The Playwright Check Suite configuration consists of specific Playwright Check S
 | `pwProjects` | `string` `string[]` | ❌ | - | Specific Playwright projects to run from your configuration |
 | `pwTags` | `string` `string[]` | ❌ | - | Tags to filter which tests to run using Playwright's grep functionality |
 | `include` | `string` `string[]` | ❌ | - | File patterns to include when bundling the test project |
+| `engine` | `Engine` | ❌ | Auto-detected, then Node.js 22 | JavaScript engine and version used to run the Playwright Check Suite |
 
 </Tab>
 <Tab title="General Check">
@@ -218,7 +219,7 @@ Defines the glob patterns for files and directories that should be included when
 new PlaywrightCheck("critical-e2e-monitor", {
   name: "Critical E2E Monitor",
   playwrightConfigPath: "../playwright.config.ts",
-  include: ['.npmrc','test-files/**'],
+  include: [".npmrc", "test-files/**"],
 })
 ```
 
@@ -230,6 +231,55 @@ Use `include` to bundle files that are not directly imported/required.
 
 </ResponseField>
 
+<ResponseField name="engine" type="Engine">
+
+The JavaScript engine and version used to run the Playwright Check Suite. Use the `Engine` helpers to select Node.js or Bun explicitly.
+
+**Usage:**
+
+<CodeGroup>
+
+```ts Node.js highlight={1,5}
+import { Engine, PlaywrightCheck } from "checkly/constructs"
+
+new PlaywrightCheck("critical-e2e-monitor", {
+  name: "Critical E2E Monitor",
+  playwrightConfigPath: "../playwright.config.ts",
+  engine: Engine.node("24"),
+})
+```
+
+```ts Bun highlight={1,5}
+import { Engine, PlaywrightCheck } from "checkly/constructs"
+
+new PlaywrightCheck("critical-e2e-monitor", {
+  name: "Critical E2E Monitor",
+  playwrightConfigPath: "../playwright.config.ts",
+  engine: Engine.bun("1.3"),
+})
+```
+
+</CodeGroup>
+
+If you omit `engine`, the Checkly CLI tries to detect it from project version files. It checks `.node-version`, `.nvmrc`, `.tool-versions` (`nodejs` or `bun`), `.bun-version`, and `package.json` `engines.node` or `engines.bun`.
+
+When both Node.js and Bun candidates are found, Node.js takes precedence. `.nvmrc` aliases such as `lts`, `lts/*`, `node`, `stable`, and `latest` are skipped.
+
+For `package.json` engine ranges, the CLI uses the minimum version from the semver range. For example, `>=22` resolves to Node.js `22`, and `>=1.3` resolves to Bun `1.3`.
+
+Detected and explicit versions are checked against Checkly's engine rules:
+
+| Engine | Supported versions | Resolution behavior |
+|--------|--------------------|---------------------|
+| Node.js | `22`, `24`, `26` | Older, EOL, non-LTS, or future major versions are remapped to the nearest supported LTS version with a warning |
+| Bun | `1.3` | Older or future `1.x` versions are remapped to `1.3` with a warning; `2.x` and newer are rejected |
+
+<Info>
+If no engine is set and the CLI cannot auto-detect one, Checkly uses the default Node.js 22 engine.
+</Info>
+
+</ResponseField>
+
 ### General Check Options
 
 <ResponseField name="name" type="string" required>

detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx

@@ -7,14 +7,14 @@ sidebarTitle: 'Custom Dependencies'
 Use the [Checkly CLI](/cli/) to turn your Playwright tests into globally distributed monitors. Checkly uses your existing `package.json` dependencies and Playwright configuration.
 
 <Info>
-**Runtime Environment**: Playwright Check Suites run in a Node.js runtime containing your custom dependencies. See the [runtime specification](/platform/runtimes/runtime-specification) for further details.
+Playwright Check Suites do not use Checkly runtimes. Browser Checks and Multistep Checks use `runtimeId` to select a managed runtime with fixed Checkly-provided dependencies. Playwright Check Suites install your project dependencies and use `engine` to select the JavaScript engine version.
 </Info>
 
 ## Using JavaScript/Node.js dependencies
 
 Checkly installs dependencies from your `package.json` and lock files. It works with [npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/), and [pnpm](https://pnpm.io/).
 
-By default, Checkly installs all dependencies (both `dependencies` and `devDependencies`). 
+By default, Checkly installs all dependencies (both `dependencies` and `devDependencies`).
 
 ```json package.json
 {
@@ -33,15 +33,15 @@ Checkly detects your package manager from your lock file:
 | Lock file           | Package manager |
 |---------------------|-----------------|
 | `package-lock.json` | npm             |
-| `pnpm-lock.yaml`    | pnpm            | 
-| `yarn.lock`         | yarn            | 
+| `pnpm-lock.yaml`    | pnpm            |
+| `yarn.lock`         | yarn            |
 
 ### Workspace support
 
 Starting from [Checkly CLI 7.1.](https://github.com/checkly/checkly-cli/releases/tag/7.1.0), Checkly supports `npm` and `pnpm` workspaces in Playwright Check Suites, while Yarn workspaces remain unsupported.
 
-If your Playwright tests are stored in a monorepo, Checkly automatically recognizes and manages dependencies based on your workspace configuration. 
-When using workspaces, packages in your workspace can depend on other packages in the same workspace, including those from the root package. Check out [pnpm workspaces docs](https://pnpm.io/workspaces)(https://pnpm.io/workspaces) or [npm workspaces docs](https://docs.npmjs.com/cli/v8/using-npm/workspaces) to get an overview on workspaces. 
+If your Playwright tests are stored in a monorepo, Checkly automatically recognizes and manages dependencies based on your workspace configuration.
+When using workspaces, packages in your workspace can depend on other packages in the same workspace, including those from the root package. See the [pnpm workspaces docs](https://pnpm.io/workspaces) or [npm workspaces docs](https://docs.npmjs.com/cli/v8/using-npm/workspaces) to learn how workspaces work.
 
 **Requirements:**
 - Place your lock file (`package-lock.json` or `pnpm-lock.yaml`) at the workspace root
@@ -251,4 +251,4 @@ If you encounter general installation errors:
 
 - Review the full error logs for specific issues
 - Ensure all dependencies are compatible with the Node.js version used by Checkly
-- Consider using a custom `installCommand` to handle complex installations
+- Consider using a custom `installCommand` to handle complex installations

platform/runtimes/overview.mdx

@@ -4,22 +4,24 @@ description: 'How Checkly runtimes work.'
 sidebarTitle: 'Overview'
 ---
 
-Checkly allows you to use JavaScript code in your [Browser checks](/detect/synthetic-monitoring/browser-checks/overview), [MultiStep Checks](/detect/synthetic-monitoring/multistep-checks/overview) and in the optional [setup & teardown scripts](/detect/synthetic-monitoring/api-checks/setup-and-teardown) you can add to your API checks.
+Checkly lets you use JavaScript code in your [Browser checks](/detect/synthetic-monitoring/browser-checks/overview), [MultiStep Checks](/detect/synthetic-monitoring/multistep-checks/overview), and optional [setup and teardown scripts](/detect/synthetic-monitoring/api-checks/setup-and-teardown) for API checks.
 
-This JavaScript code executes in a runtime environment that is managed by Checkly. This environment has access to specific Node.js versions and NPM packages, like the "latest Playwright version on Node 14". We call these environments **runtimes**.
+This JavaScript code executes in a runtime environment that is managed by Checkly. This environment includes a specific Node.js version, Playwright version, browser binaries, and selected npm packages. We call these managed environments **runtimes**.
+
+Playwright Check Suites use a different model. They do not use Checkly runtimes. They install your project dependencies from your `package.json` and lock file, and use `engine` to select the JavaScript engine version.
 
 ## Using runtimes
 
-It's pretty easy. You don't have to do anything most of the time.
+You do not have to configure runtimes for most checks.
 
 1. View all the available runtimes on the [runtimes tab in the account section](https://app.checklyhq.com/settings/account/runtimes/). See the screenshot below.
 2. There is always one runtime marked as **active**. This is the runtime all checks use, unless you decide to override this at the check or group level.
-4. Runtimes have a simple `YYYY.MM` name, e.g. `2025.04` Newer dates hold newer dependencies.
-3. Pick the runtime you want and click "Save settings". This runtime now applies to all of your checks and any new checks you create.
+3. Runtimes have a simple `YYYY.MM` name, e.g. `2026.04`. Newer dates include newer dependencies.
+4. Pick the runtime you want and click "Save settings". This runtime now applies to all of your checks and any new checks you create.
 
 ![runtimes](/images/docs/images/cli/account_runtimes.png)
 
-Note that one runtime version, e.g. `2025.04` holds all dependencies for all check types. There is no separate runtime for different types of checks.
+Note that one runtime version, e.g. `2026.04`, holds all runtime dependencies for all check types that use Checkly runtimes. There is no separate runtime for different types of checks.
 
 ## Overriding runtimes for specific checks
 
@@ -31,7 +33,9 @@ You can:
 - Select a specific runtime in the "Setup & teardown" tab for each **API check**.
 - Select a specific runtime on the "Runtimes" tab for each **check group**.
 
-> Overriding the global, account level runtime for a handful of checks is **the recommended way to check for any compatibility issues** before committing to a new, global runtime. Note the hierarchy: **check** runtime trumps **group** runtime trumps **global account** runtime.
+Playwright Check Suites do not appear in this hierarchy because they use `engine`, not `runtimeId`.
+
+> Overriding the global, account-level runtime for a few checks is **the recommended way to check for compatibility issues** before committing to a new global runtime. Note the hierarchy: the **check** runtime takes precedence over the **group** runtime, which takes precedence over the **global account** runtime.
 
 ## How we update and release new runtimes
 
@@ -61,4 +65,3 @@ NPM dependencies living in `node_modules`.
 4. Our provided Runtime packages are tested with our sandboxing for extra runtime security.
 
 If you want to see a package included in the Checkly Runtime, [please add a post on our feedback board](https://feedback.checklyhq.com/) with a package name, and your use case.
-