checkly 8.4.0 → 8.5.0

package/dist/ai-context/checkly.rules.md

@@ -6,6 +6,8 @@
 - Use the [Checkly construct reference documentation](https://www.checklyhq.com/docs/constructs/overview/).
 - Import and / or require any constructs you need in your code, such as `ApiCheck`, `BrowserCheck`, or `PlaywrightCheck` from the `checkly/constructs` package.
 - Always ground generated code and CLI commands against the official documentation and examples in this file.
+- Use `runtimeId` for Browser Checks and MultiStep Checks. Runtimes are managed Checkly execution environments with fixed Checkly-provided dependencies such as Playwright, browser binaries, and runtime libraries.
+- Use `engine` only for Playwright Check Suites. `engine` selects the JavaScript engine version that runs the user's own Playwright project.
 
 ## Using the Checkly CLI
 
@@ -19,7 +21,7 @@
 - `*.check.ts|js` - TS / JS files that define the checks.
 - `*.spec.ts|js` - TS / JS files that contain Playwright code for Browser and MultiStep checks.
 - `src/__checks__` - Default directory where all your checks are stored. Use this directory if it already exists, otherwise create a new directory for your checks.
-- `package.json` - Standard NPM project manifest.
+- `package.json` - Standard npm project manifest.
 
 Here is an example directory tree of what that would look like:
 
@@ -118,6 +120,9 @@ Email (`EmailAlertChannel`), Phone (`PhoneCallAlertChannel`), Slack (`SlackAlert
 ### `npx checkly skills configure supporting-constructs`
 Status pages (`StatusPage`), dashboards (`Dashboard`), maintenance windows (`MaintenanceWindow`), and private locations (`PrivateLocation`)
 
+### `npx checkly skills configure environment`
+Environment variables: built-in vars Checkly injects at runtime (`CHECK_ID`, `CHECK_NAME`, `REGION`, `CHECKLY_*`), user-defined variables and secrets at global/group/check scope, reference syntax (`process.env` vs `{{handlebars}}`), and the `checkly env` CLI for managing global vars.
+
 ## Important: Public URL Requirement
 
 All checks (API, Browser, URL monitors) run on **Checkly's cloud infrastructure**, not on the user's local machine. Target URLs must be publicly accessible from the internet.
@@ -284,6 +289,7 @@ Note the names: `notEmpty` (not `isNotEmpty`), `greaterThan` / `lessThan` (not `
 - Use axios for making HTTP requests.
 - Read the input credentials from env variables using `process.env`.
 - Pass auth tokens to the request object using `request.headers['key'] = AUTH_TOKEN_VALUE`.
+- For built-in env vars setup/teardown scripts receive at runtime (`CHECK_ID`, `REGION`, `RUNTIME_VERSION`, `PUBLIC_IP_V4`, etc.), see `npx checkly skills configure environment`. The API request itself doesn't run JS — use Handlebars (`{{MY_VAR}}`) in URL, headers, body, basic auth, and query params instead.
 
 ### Browser Checks
 
@@ -292,6 +298,7 @@ Note the names: `notEmpty` (not `isNotEmpty`), `greaterThan` / `lessThan` (not `
 - Use the `code.entrypoint` property to specify the path to your Playwright test file.
 - **Important:** The target URL must be publicly accessible — checks run on Checkly's cloud, not locally.
 - **Plan-gated properties:** `retryStrategy`, `runParallel`, and higher frequencies may not be available on all plans. Check entitlements matching `BROWSER_CHECKS_*` before using these. Omit any property whose entitlement is disabled. See `npx checkly skills manage` for details.
+- For env vars Checkly exposes at runtime (`CHECK_ID`, `REGION`, `RUNTIME_VERSION`, etc.), see `npx checkly skills configure environment`.
 
 **Reference:** https://www.checklyhq.com/docs/constructs/browser-check/
 
@@ -324,9 +331,54 @@ new BrowserCheck('example-browser-check', {
 ### Playwright Check Suites
 
 - Import the `PlaywrightCheck` construct from `checkly/constructs`.
+- Use Playwright Check Suites to run an existing Playwright project. Do not rewrite tests as Browser or Multistep Checks unless the user asks.
+- Set `playwrightConfigPath` relative to the `.check.ts` file that declares the construct, not the project root. If the check is in `monitoring/suites.check.ts` and the config is at the repo root, use `"../playwright.config.ts"`.
+- Use `pwProjects` only when the user wants specific Playwright projects. Values must match the Playwright project `name`, such as `"Cart & Checkout"`, not a folder or slug. Wrong names can deploy but run zero tests.
+- Use `pwTags` only when the user wants tag-based selection.
+
+#### Dependencies
+
+- Use the user's `package.json` and lock file for dependencies. Do not add dependency declarations to check code.
+- For private packages or custom registries, include the registry config file, usually `.npmrc`, with `include`.
+- The `.npmrc` should reference a Checkly environment variable such as `${NPM_TOKEN}`. Tell the user that the token must exist in Checkly before `deploy` or `trigger`.
+- Use `installCommand` only when the default package-manager install command is not enough.
+- In Checkly CLI v8.0.0 and later, `include` patterns resolve relative to the Playwright config directory, not the project root. If `playwrightConfigPath` points to a subdirectory, adjust `include` globs. Example: `playwrightConfigPath: "./e2e/playwright.config.ts"` with root `.npmrc` needs `include: ["../.npmrc"]`.
+
+#### Install troubleshooting
+
+- The execution environment is Linux and non-root, and it does not include a C/C++ compiler. Browsers are pre-installed, so never add `playwright install`, `npx playwright install`, Puppeteer browser downloads, or similar browser installation commands.
+- If `scripts.postinstall`, `scripts.prepare`, or `scripts.install` references missing files, downloads browsers, sets up git hooks, or compiles native code, set `installCommand` to skip project lifecycle scripts and rebuild dependency scripts:
+  - npm: `npm install --ignore-scripts && npm rebuild`
+  - pnpm: `pnpm install --ignore-scripts && pnpm rebuild`
+- Flag likely dependency problems before suggesting a deploy:
+  - `puppeteer` is usually unnecessary because browsers are pre-installed.
+  - Native dependencies that require a compiler, such as `sharp` or `better-sqlite3`, may fail.
+  - `fsevents` must be optional; a locked non-optional `fsevents` dependency can fail on Linux.
+  - `workspace:*` dependencies must be included in the uploaded bundle.
+  - Private registries must have auth configured through Checkly environment variables.
+
+#### Runtime model
+
+- Do not use `runtimeId` for Playwright Check Suites. Browser and Multistep Checks use `runtimeId`; Playwright Check Suites use project dependencies plus `engine`.
+- Omit `engine` unless the user explicitly asks to override the JavaScript engine or version.
+- If an engine override is needed, import `Engine` from `checkly/constructs` and use `Engine.node("24")` or `Engine.bun("1.3")`.
+- If no engine is configured or detected, Checkly defaults to Node.js 22. Node.js engine majors map to pinned patch versions: `22` -> `22.14.0`, `24` -> `24.13.1`, and `26` -> `26.2.0`.
+
+```typescript
+import { PlaywrightCheck } from "checkly/constructs"
+
+new PlaywrightCheck("checkout-suite", {
+  name: "Checkout suite",
+  playwrightConfigPath: "./e2e/playwright.config.ts",
+  // Include root .npmrc for private package or registry auth.
+  include: ["../.npmrc"],
+})
+```
 - `playwrightConfigPath` is resolved **relative to the `.check.ts` file that declares the construct**, not the project root. If your check lives in `monitoring/suites.check.ts` and your config in `playwright.config.ts` at the repo root, use `'../playwright.config.ts'`.
 - use `pwProjects` if you're tasked to reuse a Playwright project. Values must match the `name` field of each project in your `playwright.config.ts` (e.g. `'Cart & Checkout'`), **not** the directory slug. Mismatched names deploy silently and resolve to zero tests.
 - use `pwTags` if you're tasked to reuse a Playwright tag.
+- Use `include` only for non-code assets that specs read via `fs` at runtime (markdown, JSON fixtures, snapshots). Test files and anything reachable through `import` are already bundled via Playwright's project discovery and the import graph — listing them in `include` is redundant. Globs resolve **relative to the directory of `playwrightConfigPath`**, not the project root and not the `.check.ts`.
+- For env vars Checkly exposes at runtime (e.g. `CHECKLY=1` for "am I running on Checkly?"), see `npx checkly skills configure environment`.
 
 **Reference:** https://www.checklyhq.com/docs/constructs/playwright-check/
 
@@ -339,6 +391,11 @@ const playwrightChecks = new PlaywrightCheck("multi-browser-check", {
   // Playwright Check Suites support all browsers
   // defined in your `playwright.config`
   pwProjects: ["chromium", "firefox", "webkit"],
+  // Bundle non-code assets that specs read via `fs` at runtime.
+  // Test files and anything reachable through `import` are already
+  // bundled — `include` is only for files outside the import graph.
+  // Globs resolve relative to the playwright config's directory.
+  include: ["fixtures/**/*.json", "docs/**/*.md"],
 });
 ```
 
@@ -347,6 +404,7 @@ const playwrightChecks = new PlaywrightCheck("multi-browser-check", {
 - Import the `MultiStepCheck` construct from `checkly/constructs`.
 - Generate a separate `.spec.ts` file for the Playwright code referenced in the `MultiStepCheck` construct.
 - Use the `code.entrypoint` property to specify the path to your Playwright test file.
+- For env vars Checkly exposes at runtime (`CHECK_ID`, `REGION`, `RUNTIME_VERSION`, etc.), see `npx checkly skills configure environment`.
 
 **Reference:** https://www.checklyhq.com/docs/constructs/multistep-check/
 
@@ -576,6 +634,7 @@ new HeartbeatMonitor('example-heartbeat-monitor', {
 - Import the `CheckGroupV2` construct from `checkly/constructs`.
 - Check Groups are used to group checks together for easier management and organization.
 - Checks are added to Check Groups by referencing the group in the `group` property of a check.
+- **Alert channels on a group require `alertEscalationPolicy`.** If you set custom `alertChannels` on a `CheckGroupV2` without also setting `alertEscalationPolicy`, the group's channels are ignored and each check uses its own alert settings. Use `alertEscalationPolicy: 'global'` to apply the account-wide policy, or build a custom policy with `AlertEscalationBuilder` from `checkly/constructs`.
 
 **Reference:** https://www.checklyhq.com/docs/constructs/check-group/
 
@@ -773,3 +832,96 @@ export const examplePrivateLocation = new PrivateLocation('example-private-locat
   icon: 'location',
 })
 ```
+
+### Environment Variables
+
+Checks execute on Checkly's cloud infrastructure, not on the user's machine. Two sources of values are exposed at runtime: built-in variables Checkly injects, and user-defined variables managed in the project, group, check, or globally via the CLI.
+
+#### Built-in: Available in All Check Types
+
+Entries with no value are stripped.
+
+| Variable | Description |
+| --- | --- |
+| `CHECK_ID` | UUID of the check. |
+| `CHECK_NAME` | Name of the check. |
+| `CHECK_TYPE` | `BROWSER`, `MULTISTEP`, `API`, `PLAYWRIGHT`, etc. |
+| `CHECK_RUN_ID` | ID of the run. Format varies by check type (UUID for Playwright Check Suites, numeric ID for browser/multistep). |
+| `CHECK_RESULT_ID` | UUID of the result record. |
+| `ACCOUNT_ID` | UUID of the Checkly account. |
+| `REQUEST_URL` | The check's request URL (mainly relevant for API checks). |
+| `GROUP_BASE_URL` | Base URL of the check's group, if any. |
+| `CLIENT_CERTIFICATE` | Client cert if configured. |
+| `ENVIRONMENT_NAME` | Deployment environment name. Set only for CI/CD-triggered runs. |
+| `DEPLOYMENT_ID` | Deployment UUID. Set only for CI/CD-triggered runs. |
+
+#### Built-in: Browser Checks, MultiStep Checks, API Setup/Teardown
+
+In addition to the variables above:
+
+| Variable | Description |
+| --- | --- |
+| `REGION` | AWS region of the runner. |
+| `RUNTIME_VERSION` | Runtime version string (e.g. `2025.04`). |
+| `PUBLIC_IP_V4` | Public IPv4 of the runner. Value has a trailing newline — call `.trim()` before using. |
+| `PUBLIC_IP_V6` | Public IPv6 of the runner. Value has a trailing newline — call `.trim()` before using. |
+
+#### Built-in: Playwright Check Suites
+
+In addition to the variables in the first table:
+
+| Variable | Description |
+| --- | --- |
+| `CHECKLY` | Always `1`. Cleanest "am I running on Checkly?" signal. |
+| `CHECKLY_CHECK_ID` | UUID of the check. Mirrors `CHECK_ID`. |
+| `CHECKLY_REGION` | Region where the run executes. |
+| `CHECKLY_RUN_SOURCE` | What triggered the run (CLI deploy, deployment, group run, manual schedule, scheduler, test, API). |
+| `CI` | `1` for CLI runs (`npx checkly test`, `npx checkly trigger`) and deployment-triggered runs. |
+
+Docs: https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/environment-variables/
+
+#### User-Defined Variables
+
+User-defined variables live at three scopes. Precedence: **check overrides group overrides global**.
+
+- **Global** — available to every check and alert channel in the account. Managed in the UI or via `npx checkly env *`.
+- **Group** — scoped to a check group and all its checks. Defined on the `CheckGroupV2` construct.
+- **Check** — scoped to a single check. Defined on the construct.
+
+##### Variables vs. Secrets
+
+- **Variables** are plaintext: visible in the UI, on result pages, in logs, and exportable via CLI / API.
+- **Secrets** are encrypted at rest and never visible after creation — not in the UI, not in logs, not retrievable via CLI or API. Secrets require runtime `2024.09` or later (`3.3.4+` for Private Locations, CLI `4.9.0+`).
+- **Locked** variables are encrypted at rest and restricted to Read & Write, Admin, or Owner roles.
+
+Docs: https://www.checklyhq.com/docs/platform/variables/
+
+#### Reference Syntax
+
+How to read a variable depends on the context:
+
+| Context | Syntax |
+| --- | --- |
+| Browser checks, MultiStep checks, API setup/teardown scripts | `process.env.MY_VAR` |
+| API check requests (URL, headers, body, query params, basic auth) | `{{MY_VAR}}` |
+| API check requests where URI encoding is unwanted | `{{{MY_VAR}}}` |
+| Webhook alert channel payloads | `{{MY_VAR}}` |
+
+#### Managing Global Variables via the CLI
+
+`npx checkly env` manages **global** account variables. Group- and check-level variables are managed via the UI or directly on the construct.
+
+| Command | Description |
+| --- | --- |
+| `npx checkly env add <key> <value> [--locked\|-l] [--secret\|-s]` | Create a variable. |
+| `npx checkly env update <key> <value> [--locked\|-l] [--secret\|-s]` | Update an existing variable. |
+| `npx checkly env ls` | List all account variables; secrets are masked. |
+| `npx checkly env pull [filename] [--force\|-f]` | Export to a local file (default `.env`). |
+| `npx checkly env rm <key> [--force\|-f]` | Delete a variable. |
+
+Docs: https://www.checklyhq.com/docs/cli/checkly-env/
+
+#### Common Use
+
+- Gate behavior between local runs and Checkly cloud by checking `process.env.CHECK_ID` (set for every check type).
+- Differentiate retry counts, reporter output, or fixture loading by environment without defining a custom env var.

package/dist/ai-context/context.d.ts

@@ -37,10 +37,16 @@ export declare const REFERENCES: readonly [{
 }, {
     readonly id: "configure-supporting-constructs";
     readonly description: "Status pages (`StatusPage`), dashboards (`Dashboard`), maintenance windows (`MaintenanceWindow`), and private locations (`PrivateLocation`)";
+}, {
+    readonly id: "configure-environment";
+    readonly description: "Environment variables: built-in vars Checkly injects at runtime (`CHECK_ID`, `CHECK_NAME`, `REGION`, `CHECKLY_*`), user-defined variables and secrets at global/group/check scope, reference syntax (`process.env` vs `{{handlebars}}`), and the `checkly env` CLI for managing global vars.";
 }];
 export declare const INVESTIGATE_REFERENCES: readonly [{
     readonly id: "investigate-checks";
     readonly description: "Inspecting checks (`checks list`, `checks get`) and triggering on-demand runs";
+}, {
+    readonly id: "investigate-test-sessions";
+    readonly description: "Run and inspect recorded test sessions, drill into test-session error groups, run RCA, and retrieve result assets";
 }];
 export declare const COMMUNICATE_REFERENCES: readonly [{
     readonly id: "communicate-incidents";
@@ -102,13 +108,19 @@ export declare const ACTIONS: readonly [{
     }, {
         readonly id: "configure-supporting-constructs";
         readonly description: "Status pages (`StatusPage`), dashboards (`Dashboard`), maintenance windows (`MaintenanceWindow`), and private locations (`PrivateLocation`)";
+    }, {
+        readonly id: "configure-environment";
+        readonly description: "Environment variables: built-in vars Checkly injects at runtime (`CHECK_ID`, `CHECK_NAME`, `REGION`, `CHECKLY_*`), user-defined variables and secrets at global/group/check scope, reference syntax (`process.env` vs `{{handlebars}}`), and the `checkly env` CLI for managing global vars.";
     }];
 }, {
     readonly id: "investigate";
-    readonly description: "Access check status, analyze failures, and investigate errors.";
+    readonly description: "Access check and test-session status, analyze failures, and investigate errors.";
     readonly references: readonly [{
         readonly id: "investigate-checks";
         readonly description: "Inspecting checks (`checks list`, `checks get`) and triggering on-demand runs";
+    }, {
+        readonly id: "investigate-test-sessions";
+        readonly description: "Run and inspect recorded test sessions, drill into test-session error groups, run RCA, and retrieve result assets";
     }];
 }, {
     readonly id: "communicate";

package/dist/ai-context/context.js

@@ -51,12 +51,20 @@ export const REFERENCES = [
         id: 'configure-supporting-constructs',
         description: 'Status pages (`StatusPage`), dashboards (`Dashboard`), maintenance windows (`MaintenanceWindow`), and private locations (`PrivateLocation`)',
     },
+    {
+        id: 'configure-environment',
+        description: 'Environment variables: built-in vars Checkly injects at runtime (`CHECK_ID`, `CHECK_NAME`, `REGION`, `CHECKLY_*`), user-defined variables and secrets at global/group/check scope, reference syntax (`process.env` vs `{{handlebars}}`), and the `checkly env` CLI for managing global vars.',
+    },
 ];
 export const INVESTIGATE_REFERENCES = [
     {
         id: 'investigate-checks',
         description: 'Inspecting checks (`checks list`, `checks get`) and triggering on-demand runs',
     },
+    {
+        id: 'investigate-test-sessions',
+        description: 'Run and inspect recorded test sessions, drill into test-session error groups, run RCA, and retrieve result assets',
+    },
 ];
 export const COMMUNICATE_REFERENCES = [
     {
@@ -90,7 +98,7 @@ export const ACTIONS = [
     },
     {
         id: 'investigate',
-        description: 'Access check status, analyze failures, and investigate errors.',
+        description: 'Access check and test-session status, analyze failures, and investigate errors.',
         references: INVESTIGATE_REFERENCES,
     },
     {
@@ -162,6 +170,11 @@ const playwrightChecks = new PlaywrightCheck("multi-browser-check", {
   // Playwright Check Suites support all browsers
   // defined in your \`playwright.config\`
   pwProjects: ["chromium", "firefox", "webkit"],
+  // Bundle non-code assets that specs read via \`fs\` at runtime.
+  // Test files and anything reachable through \`import\` are already
+  // bundled — \`include\` is only for files outside the import graph.
+  // Globs resolve relative to the playwright config's directory.
+  include: ["fixtures/**/*.json", "docs/**/*.md"],
 });
 `,
         reference: 'https://www.checklyhq.com/docs/constructs/playwright-check/',

package/dist/ai-context/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/ai-context/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/ai-context/context.ts"],"names":[],"mappings":"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"}

package/dist/ai-context/public-skills/checkly/SKILL.md

@@ -14,6 +14,8 @@ Then run `npx checkly skills <action>` to load up-to-date details for the action
 
 Use `npx checkly skills install` to install this skill into your project (supports Claude Code, Cursor, Codex and more).
 
+For recorded test-session investigations, run `npx checkly skills investigate test-sessions`.
+
 ## Progressive Disclosure via `npx checkly skills`
 
 The skill is structured for efficient context usage:
@@ -101,7 +103,7 @@ Learn how to initialize and set up a new Checkly CLI project from scratch.
 Learn how to create and manage monitoring checks using Checkly constructs and the CLI.
 
 ### `npx checkly skills investigate`
-Access check status, analyze failures, and investigate errors.
+Access check and test-session status, analyze failures, and investigate errors.
 
 ### `npx checkly skills communicate`
 Open incidents and lead customer communications via status pages.

package/dist/ai-context/skills-command/references/configure-api-checks.md

@@ -70,3 +70,4 @@ Note the names: `notEmpty` (not `isNotEmpty`), `greaterThan` / `lessThan` (not `
 - Use axios for making HTTP requests.
 - Read the input credentials from env variables using `process.env`.
 - Pass auth tokens to the request object using `request.headers['key'] = AUTH_TOKEN_VALUE`.
+- For built-in env vars setup/teardown scripts receive at runtime (`CHECK_ID`, `REGION`, `RUNTIME_VERSION`, `PUBLIC_IP_V4`, etc.), see `npx checkly skills configure environment`. The API request itself doesn't run JS — use Handlebars (`{{MY_VAR}}`) in URL, headers, body, basic auth, and query params instead.

package/dist/ai-context/skills-command/references/configure-browser-checks.md

@@ -5,6 +5,7 @@
 - Use the `code.entrypoint` property to specify the path to your Playwright test file.
 - **Important:** The target URL must be publicly accessible — checks run on Checkly's cloud, not locally.
 - **Plan-gated properties:** `retryStrategy`, `runParallel`, and higher frequencies may not be available on all plans. Check entitlements matching `BROWSER_CHECKS_*` before using these. Omit any property whose entitlement is disabled. See `npx checkly skills manage` for details.
+- For env vars Checkly exposes at runtime (`CHECK_ID`, `REGION`, `RUNTIME_VERSION`, etc.), see `npx checkly skills configure environment`.
 
 **Reference:** https://www.checklyhq.com/docs/constructs/browser-check/
 

package/dist/ai-context/skills-command/references/configure-check-groups.md

@@ -3,6 +3,7 @@
 - Import the `CheckGroupV2` construct from `checkly/constructs`.
 - Check Groups are used to group checks together for easier management and organization.
 - Checks are added to Check Groups by referencing the group in the `group` property of a check.
+- **Alert channels on a group require `alertEscalationPolicy`.** If you set custom `alertChannels` on a `CheckGroupV2` without also setting `alertEscalationPolicy`, the group's channels are ignored and each check uses its own alert settings. Use `alertEscalationPolicy: 'global'` to apply the account-wide policy, or build a custom policy with `AlertEscalationBuilder` from `checkly/constructs`.
 
 **Reference:** https://www.checklyhq.com/docs/constructs/check-group/
 

package/dist/ai-context/skills-command/references/configure-environment.md

@@ -0,0 +1,92 @@
+# Environment Variables
+
+Checks execute on Checkly's cloud infrastructure, not on the user's machine. Two sources of values are exposed at runtime: built-in variables Checkly injects, and user-defined variables managed in the project, group, check, or globally via the CLI.
+
+## Built-in: Available in All Check Types
+
+Entries with no value are stripped.
+
+| Variable | Description |
+| --- | --- |
+| `CHECK_ID` | UUID of the check. |
+| `CHECK_NAME` | Name of the check. |
+| `CHECK_TYPE` | `BROWSER`, `MULTISTEP`, `API`, `PLAYWRIGHT`, etc. |
+| `CHECK_RUN_ID` | ID of the run. Format varies by check type (UUID for Playwright Check Suites, numeric ID for browser/multistep). |
+| `CHECK_RESULT_ID` | UUID of the result record. |
+| `ACCOUNT_ID` | UUID of the Checkly account. |
+| `REQUEST_URL` | The check's request URL (mainly relevant for API checks). |
+| `GROUP_BASE_URL` | Base URL of the check's group, if any. |
+| `CLIENT_CERTIFICATE` | Client cert if configured. |
+| `ENVIRONMENT_NAME` | Deployment environment name. Set only for CI/CD-triggered runs. |
+| `DEPLOYMENT_ID` | Deployment UUID. Set only for CI/CD-triggered runs. |
+
+## Built-in: Browser Checks, MultiStep Checks, API Setup/Teardown
+
+In addition to the variables above:
+
+| Variable | Description |
+| --- | --- |
+| `REGION` | AWS region of the runner. |
+| `RUNTIME_VERSION` | Runtime version string (e.g. `2025.04`). |
+| `PUBLIC_IP_V4` | Public IPv4 of the runner. Value has a trailing newline — call `.trim()` before using. |
+| `PUBLIC_IP_V6` | Public IPv6 of the runner. Value has a trailing newline — call `.trim()` before using. |
+
+## Built-in: Playwright Check Suites
+
+In addition to the variables in the first table:
+
+| Variable | Description |
+| --- | --- |
+| `CHECKLY` | Always `1`. Cleanest "am I running on Checkly?" signal. |
+| `CHECKLY_CHECK_ID` | UUID of the check. Mirrors `CHECK_ID`. |
+| `CHECKLY_REGION` | Region where the run executes. |
+| `CHECKLY_RUN_SOURCE` | What triggered the run (CLI deploy, deployment, group run, manual schedule, scheduler, test, API). |
+| `CI` | `1` for CLI runs (`npx checkly test`, `npx checkly trigger`) and deployment-triggered runs. |
+
+Docs: https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/environment-variables/
+
+## User-Defined Variables
+
+User-defined variables live at three scopes. Precedence: **check overrides group overrides global**.
+
+- **Global** — available to every check and alert channel in the account. Managed in the UI or via `npx checkly env *`.
+- **Group** — scoped to a check group and all its checks. Defined on the `CheckGroupV2` construct.
+- **Check** — scoped to a single check. Defined on the construct.
+
+### Variables vs. Secrets
+
+- **Variables** are plaintext: visible in the UI, on result pages, in logs, and exportable via CLI / API.
+- **Secrets** are encrypted at rest and never visible after creation — not in the UI, not in logs, not retrievable via CLI or API. Secrets require runtime `2024.09` or later (`3.3.4+` for Private Locations, CLI `4.9.0+`).
+- **Locked** variables are encrypted at rest and restricted to Read & Write, Admin, or Owner roles.
+
+Docs: https://www.checklyhq.com/docs/platform/variables/
+
+## Reference Syntax
+
+How to read a variable depends on the context:
+
+| Context | Syntax |
+| --- | --- |
+| Browser checks, MultiStep checks, API setup/teardown scripts | `process.env.MY_VAR` |
+| API check requests (URL, headers, body, query params, basic auth) | `{{MY_VAR}}` |
+| API check requests where URI encoding is unwanted | `{{{MY_VAR}}}` |
+| Webhook alert channel payloads | `{{MY_VAR}}` |
+
+## Managing Global Variables via the CLI
+
+`npx checkly env` manages **global** account variables. Group- and check-level variables are managed via the UI or directly on the construct.
+
+| Command | Description |
+| --- | --- |
+| `npx checkly env add <key> <value> [--locked\|-l] [--secret\|-s]` | Create a variable. |
+| `npx checkly env update <key> <value> [--locked\|-l] [--secret\|-s]` | Update an existing variable. |
+| `npx checkly env ls` | List all account variables; secrets are masked. |
+| `npx checkly env pull [filename] [--force\|-f]` | Export to a local file (default `.env`). |
+| `npx checkly env rm <key> [--force\|-f]` | Delete a variable. |
+
+Docs: https://www.checklyhq.com/docs/cli/checkly-env/
+
+## Common Use
+
+- Gate behavior between local runs and Checkly cloud by checking `process.env.CHECK_ID` (set for every check type).
+- Differentiate retry counts, reporter output, or fixture loading by environment without defining a custom env var.

package/dist/ai-context/skills-command/references/configure-multistep-checks.md

@@ -3,6 +3,7 @@
 - Import the `MultiStepCheck` construct from `checkly/constructs`.
 - Generate a separate `.spec.ts` file for the Playwright code referenced in the `MultiStepCheck` construct.
 - Use the `code.entrypoint` property to specify the path to your Playwright test file.
+- For env vars Checkly exposes at runtime (`CHECK_ID`, `REGION`, `RUNTIME_VERSION`, etc.), see `npx checkly skills configure environment`.
 
 **Reference:** https://www.checklyhq.com/docs/constructs/multistep-check/
 

package/dist/ai-context/skills-command/references/configure-playwright-checks.md

@@ -1,9 +1,54 @@
 # Playwright Check Suites
 
 - Import the `PlaywrightCheck` construct from `checkly/constructs`.
+- Use Playwright Check Suites to run an existing Playwright project. Do not rewrite tests as Browser or Multistep Checks unless the user asks.
+- Set `playwrightConfigPath` relative to the `.check.ts` file that declares the construct, not the project root. If the check is in `monitoring/suites.check.ts` and the config is at the repo root, use `"../playwright.config.ts"`.
+- Use `pwProjects` only when the user wants specific Playwright projects. Values must match the Playwright project `name`, such as `"Cart & Checkout"`, not a folder or slug. Wrong names can deploy but run zero tests.
+- Use `pwTags` only when the user wants tag-based selection.
+
+## Dependencies
+
+- Use the user's `package.json` and lock file for dependencies. Do not add dependency declarations to check code.
+- For private packages or custom registries, include the registry config file, usually `.npmrc`, with `include`.
+- The `.npmrc` should reference a Checkly environment variable such as `${NPM_TOKEN}`. Tell the user that the token must exist in Checkly before `deploy` or `trigger`.
+- Use `installCommand` only when the default package-manager install command is not enough.
+- In Checkly CLI v8.0.0 and later, `include` patterns resolve relative to the Playwright config directory, not the project root. If `playwrightConfigPath` points to a subdirectory, adjust `include` globs. Example: `playwrightConfigPath: "./e2e/playwright.config.ts"` with root `.npmrc` needs `include: ["../.npmrc"]`.
+
+## Install troubleshooting
+
+- The execution environment is Linux and non-root, and it does not include a C/C++ compiler. Browsers are pre-installed, so never add `playwright install`, `npx playwright install`, Puppeteer browser downloads, or similar browser installation commands.
+- If `scripts.postinstall`, `scripts.prepare`, or `scripts.install` references missing files, downloads browsers, sets up git hooks, or compiles native code, set `installCommand` to skip project lifecycle scripts and rebuild dependency scripts:
+  - npm: `npm install --ignore-scripts && npm rebuild`
+  - pnpm: `pnpm install --ignore-scripts && pnpm rebuild`
+- Flag likely dependency problems before suggesting a deploy:
+  - `puppeteer` is usually unnecessary because browsers are pre-installed.
+  - Native dependencies that require a compiler, such as `sharp` or `better-sqlite3`, may fail.
+  - `fsevents` must be optional; a locked non-optional `fsevents` dependency can fail on Linux.
+  - `workspace:*` dependencies must be included in the uploaded bundle.
+  - Private registries must have auth configured through Checkly environment variables.
+
+## Runtime model
+
+- Do not use `runtimeId` for Playwright Check Suites. Browser and Multistep Checks use `runtimeId`; Playwright Check Suites use project dependencies plus `engine`.
+- Omit `engine` unless the user explicitly asks to override the JavaScript engine or version.
+- If an engine override is needed, import `Engine` from `checkly/constructs` and use `Engine.node("24")` or `Engine.bun("1.3")`.
+- If no engine is configured or detected, Checkly defaults to Node.js 22. Node.js engine majors map to pinned patch versions: `22` -> `22.14.0`, `24` -> `24.13.1`, and `26` -> `26.2.0`.
+
+```typescript
+import { PlaywrightCheck } from "checkly/constructs"
+
+new PlaywrightCheck("checkout-suite", {
+  name: "Checkout suite",
+  playwrightConfigPath: "./e2e/playwright.config.ts",
+  // Include root .npmrc for private package or registry auth.
+  include: ["../.npmrc"],
+})
+```
 - `playwrightConfigPath` is resolved **relative to the `.check.ts` file that declares the construct**, not the project root. If your check lives in `monitoring/suites.check.ts` and your config in `playwright.config.ts` at the repo root, use `'../playwright.config.ts'`.
 - use `pwProjects` if you're tasked to reuse a Playwright project. Values must match the `name` field of each project in your `playwright.config.ts` (e.g. `'Cart & Checkout'`), **not** the directory slug. Mismatched names deploy silently and resolve to zero tests.
 - use `pwTags` if you're tasked to reuse a Playwright tag.
+- Use `include` only for non-code assets that specs read via `fs` at runtime (markdown, JSON fixtures, snapshots). Test files and anything reachable through `import` are already bundled via Playwright's project discovery and the import graph — listing them in `include` is redundant. Globs resolve **relative to the directory of `playwrightConfigPath`**, not the project root and not the `.check.ts`.
+- For env vars Checkly exposes at runtime (e.g. `CHECKLY=1` for "am I running on Checkly?"), see `npx checkly skills configure environment`.
 
 **Reference:** https://www.checklyhq.com/docs/constructs/playwright-check/
 
@@ -16,5 +61,10 @@ const playwrightChecks = new PlaywrightCheck("multi-browser-check", {
   // Playwright Check Suites support all browsers
   // defined in your `playwright.config`
   pwProjects: ["chromium", "firefox", "webkit"],
+  // Bundle non-code assets that specs read via `fs` at runtime.
+  // Test files and anything reachable through `import` are already
+  // bundled — `include` is only for files outside the import graph.
+  // Globs resolve relative to the playwright config's directory.
+  include: ["fixtures/**/*.json", "docs/**/*.md"],
 });
 ```

package/dist/ai-context/skills-command/references/configure.md

@@ -6,6 +6,8 @@
 - Use the [Checkly construct reference documentation](https://www.checklyhq.com/docs/constructs/overview/).
 - Import and / or require any constructs you need in your code, such as `ApiCheck`, `BrowserCheck`, or `PlaywrightCheck` from the `checkly/constructs` package.
 - Always ground generated code and CLI commands against the official documentation and examples in this file.
+- Use `runtimeId` for Browser Checks and MultiStep Checks. Runtimes are managed Checkly execution environments with fixed Checkly-provided dependencies such as Playwright, browser binaries, and runtime libraries.
+- Use `engine` only for Playwright Check Suites. `engine` selects the JavaScript engine version that runs the user's own Playwright project.
 
 ## Using the Checkly CLI
 
@@ -19,7 +21,7 @@
 - `*.check.ts|js` - TS / JS files that define the checks.
 - `*.spec.ts|js` - TS / JS files that contain Playwright code for Browser and MultiStep checks.
 - `src/__checks__` - Default directory where all your checks are stored. Use this directory if it already exists, otherwise create a new directory for your checks.
-- `package.json` - Standard NPM project manifest.
+- `package.json` - Standard npm project manifest.
 
 Here is an example directory tree of what that would look like:
 
@@ -118,6 +120,9 @@ Email (`EmailAlertChannel`), Phone (`PhoneCallAlertChannel`), Slack (`SlackAlert
 ### `npx checkly skills configure supporting-constructs`
 Status pages (`StatusPage`), dashboards (`Dashboard`), maintenance windows (`MaintenanceWindow`), and private locations (`PrivateLocation`)
 
+### `npx checkly skills configure environment`
+Environment variables: built-in vars Checkly injects at runtime (`CHECK_ID`, `CHECK_NAME`, `REGION`, `CHECKLY_*`), user-defined variables and secrets at global/group/check scope, reference syntax (`process.env` vs `{{handlebars}}`), and the `checkly env` CLI for managing global vars.
+
 ## Important: Public URL Requirement
 
 All checks (API, Browser, URL monitors) run on **Checkly's cloud infrastructure**, not on the user's local machine. Target URLs must be publicly accessible from the internet.