checkly 0.0.0-canary.7166ed8

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

@@ -0,0 +1,916 @@
+# Checkly Monitoring
+
+- Refer to docs for Checkly CLI v6.0.0 and above.
+- Check the Checkly CLI output to figure out into which folder the setup was generated.
+- Use the [Checkly CLI reference documentation](https://www.checklyhq.com/docs/cli/overview/).
+- 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
+
+- Use `npx checkly` instead of installing the Checkly CLI globally.
+- NEVER make up commands that do not exist.
+- Use `npx checkly init` to set up Checkly in an existing project.
+
+## Project Structure
+
+- `checkly.config.ts` - Mandatory global project and CLI configuration. We recommend using TypeScript.
+- `*.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.
+
+Here is an example directory tree of what that would look like:
+
+```
+.
+|-- checkly.config.ts
+|-- package.json
+`-- src
+    `-- __checks__
+|-- alert-channels.ts
+|-- api-check.check.ts
+`-- homepage.spec.ts
+```
+
+The `checkly.config.ts` at the root of your project defines a range of defaults for all your checks.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/project/
+
+```typescript
+import { defineConfig } from 'checkly'
+import { Frequency } from 'checkly/constructs'
+
+export default defineConfig({
+  projectName: "Production Monitoring Suite",
+  logicalId: "prod-monitoring-2025",
+  repoUrl: "https://github.com/acme/monitoring",
+  checks: {
+    activated: true,
+    muted: false,
+    runtimeId: "2025.04",
+    frequency: Frequency.EVERY_10M,
+    locations: ["us-east-1", "eu-west-1", "ap-southeast-1"],
+    tags: ["production", "critical"],
+    checkMatch: "**/__checks__/*.check.ts",
+    ignoreDirectoriesMatch: ["node_modules/**", "dist/**"],
+    playwrightConfig: {
+      use: {
+        baseURL: "https://app.example.com",
+      },
+    },
+    browserChecks: {
+      frequency: Frequency.EVERY_30M,
+      testMatch: "**/__tests__/*.spec.ts",
+    },
+  },
+  cli: {
+    runLocation: "eu-west-1",
+    privateRunLocation: "private-dc1",
+    retries: 2,
+  },
+})
+```
+
+## Check and Monitor Constructs
+
+Parse and read further reference documentation when tasked with creating or managing any of the following Checkly constructs.
+
+If the Checkly CLI is installed (`npx checkly version`), use `npx checkly skills configure [CONSTRUCT]` to access up-to-date information:
+
+### `npx checkly skills configure agentic-checks`
+Agentic Check construct (`AgenticCheck`) for AI-powered prompt-driven monitoring with skill and env var allowlists
+
+### `npx checkly skills configure api-checks`
+Api Check construct (`ApiCheck`), assertions, and authentication setup scripts
+
+### `npx checkly skills configure browser-checks`
+Browser Check construct (`BrowserCheck`) with Playwright test files
+
+### `npx checkly skills configure playwright-checks`
+Playwright Check Suite construct (`PlaywrightCheck`) for multi-browser test suites
+
+### `npx checkly skills configure multistep-checks`
+Multistep Check construct (`MultiStepCheck`) for complex user flows
+
+### `npx checkly skills configure tcp-monitors`
+TCP Monitor construct (`TcpMonitor`) with assertions
+
+### `npx checkly skills configure url-monitors`
+URL Monitor construct (`UrlMonitor`) with assertions
+
+### `npx checkly skills configure dns-monitors`
+DNS Monitor construct (`DnsMonitor`) with assertions
+
+### `npx checkly skills configure icmp-monitors`
+ICMP Monitor construct (`IcmpMonitor`) with latency and packet loss assertions
+
+### `npx checkly skills configure heartbeat-monitors`
+Heartbeat Monitor construct (`HeartbeatMonitor`)
+
+### `npx checkly skills configure check-groups`
+CheckGroupV2 construct (`CheckGroupV2`) for organizing checks
+
+### `npx checkly skills configure alert-channels`
+Email (`EmailAlertChannel`), Phone (`PhoneCallAlertChannel`), Slack App (`SlackAppAlertChannel`), and other alert channels
+
+### `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.
+
+- `localhost` and private network URLs will **not work** with `npx checkly test` or `npx checkly deploy`
+- For local development, suggest: tunneling tools (ngrok, cloudflare tunnel), preview/staging deployments, or CI preview URLs
+- Always confirm with the user that their target URLs are publicly reachable before creating checks
+
+## Check Locations and Plan Entitlements
+
+Not all features and locations are available on all plans. **Before configuring checks, run:**
+
+```bash
+npx checkly account plan --output json
+```
+
+This returns your exact entitlements and available locations. Use only locations where `available` is `true` in the `locations.all` array. If a feature is disabled, the response includes an `upgradeUrl` to share with the user.
+
+Run `npx checkly skills manage plan` for the full reference.
+
+## Testing and Debugging
+
+- Test checks using the `npx checkly test` command. Pass environment variables with the `-e` flag, results are recorded by default (use `--no-record` to skip), and use `--verbose` to see all errors.
+
+## Deploying
+
+- Deploy checks using the `npx checkly deploy` command. Use `--output` to see the created, updated, and deleted resources. Use `--verbose` to also include each resource's name and physical ID (UUID), which is useful for programmatically referencing deployed resources (e.g. `npx checkly checks get <id>`).
+
+### Agentic Checks
+
+- Import the `AgenticCheck` construct from `checkly/constructs`.
+- Agentic checks are AI-powered: instead of writing code, you describe what the check should do in natural language with the `prompt` property. The agent decides how to satisfy the prompt at runtime.
+- Write prompts as concrete imperative steps, not vague goals. Tell the agent which URL to navigate to and what specific signals confirm success — for example, "Navigate to https://example.com/pricing and verify that at least three plan tiers are displayed", not "Check that pricing works".
+- Keep prompts under 10000 characters. The construct will fail validation otherwise.
+- **Frequency is entitlement-gated by the backend.** You can configure the same `frequency` values as other checks, including `Frequency.EVERY_5M` / `5`. The backend enforces the fastest cadence available to the account.
+- **Locations are entitlement-gated by the backend.** You can pass `locations` just like other public checks. The backend enforces the allowed number of regions for the account. `privateLocations` are not supported.
+- **Several common check fields are intentionally omitted** from `AgenticCheckProps`: `runParallel`, `retryStrategy`, `shouldFail`, `doubleCheck`, `triggerIncident`, and `groupId`. The platform does not yet honor these for agentic checks. Setting them in the construct is a TypeScript error.
+- **Important:** The target URL must be publicly accessible. Checks run on Checkly's cloud infrastructure, not locally. If the user is developing against localhost, suggest a tunneling tool (ngrok, cloudflare tunnel) or a preview/staging deployment.
+- **Plan-gated:** Agentic checks require the `AGENTIC_CHECKS` entitlement on the account. Run `npx checkly skills manage` to check entitlements before using.
+
+#### `agentRuntime` skills
+
+`agentRuntime` is used to add skills the agent may use at execution time.
+
+```typescript
+agentRuntime: {
+  // Additional skills to load on top of the runner's defaults (the
+  // `playwright-cli` skill is preloaded automatically — you don't need
+  // to declare it). Each entry is passed verbatim to `npx skills add`
+  // on the runner, so any third-party skill published to https://skills.sh
+  // works — not just Checkly's own. Supported identifier forms:
+  //   - full URL form:   'https://skills.sh/microsoft/playwright-cli/playwright-cli'
+  //   - owner/repo form: 'addyosmani/web-quality-skills'
+  //   - plain name:      'cost-optimization'
+  skills: ['addyosmani/web-quality-skills'],
+},
+```
+
+- Reference Checkly environment variables directly in the prompt with double brackets, for example `{{ENVIRONMENT_URL}}`.
+- The runner installs each skill via `npx skills add` at the start of every check run. The CLI does not validate the skill identifier at deploy time, so a typo will not surface until the first run.
+- The `playwright-cli` skill is preloaded for every agentic check. Only declare additional skills here.
+
+#### Assertion rules
+
+The agent generates its own assertion rules on the first successful run, and the platform persists them server-side. **The CLI construct does not expose assertion rules** — do not try to set them. They survive across deploys: importing an existing agentic check via `checkly import` will not surface them in the generated TypeScript, and a subsequent deploy of that file will not erase them on the backend.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/agentic-check/
+
+```typescript
+import { AgenticCheck, AlertEscalationBuilder, Frequency } from 'checkly/constructs'
+
+new AgenticCheck('example-agentic-check', {
+  name: 'Example Agentic Check',
+  prompt: 'Navigate to https://www.checklyhq.com/pricing and verify that at least three plan tiers are displayed on the page.',
+  activated: true,
+  locations: [
+    'us-east-1',
+    'eu-west-1',
+    'ap-southeast-1',
+  ],
+  tags: [
+    'app:webshop',
+  ],
+  frequency: Frequency.EVERY_5M,
+  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
+    amount: 0,
+    interval: 5,
+  }, {
+    enabled: false,
+    percentage: 10,
+  }),
+})
+```
+
+### API Checks
+
+- Import the `ApiCheck` construct from `checkly/constructs`.
+- When adding `assertions`, always use `AssertionBuilder` class for API Checks. Import it from `checkly/constructs`.
+- When referencing environment variables always use the handlebar syntax `{{MY_ENV_VAR}}`.
+- When referencing secrets always use the handlebar syntax `{{MY_SECRET}}`.
+- If endpoints require authentication ask the user which authentication method to use and then generate a setupScript to authenticate the given requests.
+- Referenced `setup-script.ts` and `teardown-script.ts` for API checks must be plain ts files and not export anything.
+- Check in the code if API endpoints require authentication.
+- **Important:** The target URL must be publicly accessible. Checks run on Checkly's cloud infrastructure, not locally. If the user is developing against localhost, suggest a tunneling tool (ngrok, cloudflare tunnel) or a preview/staging deployment.
+- **Plan-gated properties:** `retryStrategy`, `runParallel`, and higher frequencies may not be available on all plans. Check entitlements matching `API_CHECKS_*` before using these. Omit any property whose entitlement is disabled. See `npx checkly skills manage` for details.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/api-check/
+
+```typescript
+import { AlertEscalationBuilder, ApiCheck, Frequency, RetryStrategyBuilder } from 'checkly/constructs'
+
+new ApiCheck('example-api-check', {
+  name: 'Example API Check',
+  setupScript: {
+    entrypoint: './setup-script.ts',
+  },
+  tearDownScript: {
+    entrypoint: './teardown-script.ts',
+  },
+  degradedResponseTime: 5000,
+  maxResponseTime: 20000,
+  activated: true,
+  locations: [
+    'eu-central-1',
+    'eu-west-2',
+  ],
+  frequency: Frequency.EVERY_5M,
+  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
+    amount: 0,
+    interval: 5,
+  }, {
+    enabled: false,
+    percentage: 10,
+  }),
+  retryStrategy: RetryStrategyBuilder.noRetries(),
+  runParallel: true,
+  request: {
+    url: 'INSERT_URL',
+    method: 'GET',
+  },
+})
+```
+
+#### AssertionBuilder Reference
+
+`AssertionBuilder` provides methods to assert on API responses. Available methods:
+
+- `AssertionBuilder.statusCode()` — Numeric. Assert on HTTP status code. Example: `.equals(200)`, `.greaterThan(199)`
+- `AssertionBuilder.jsonBody(path)` — General. Assert on JSON body using JSONPath. Example: `AssertionBuilder.jsonBody('$.id').isNotNull()`
+- `AssertionBuilder.textBody()` — General. Assert on raw text body. Example: `.contains('OK')`
+- `AssertionBuilder.headers(name)` — General. Assert on response headers. Example: `AssertionBuilder.headers('content-type').contains('application/json')`
+- `AssertionBuilder.responseTime()` — Numeric. Assert on response time in ms. Example: `.lessThan(2000)`
+
+Two builder types are returned, with different comparators. Use only methods from the matching set — calling a missing method (e.g. `.isNotEmpty()`, `.isGreaterThan()`) compiles but fails at runtime:
+
+- **Numeric** (`statusCode`, `responseTime`): `.equals()`, `.notEquals()`, `.greaterThan()`, `.lessThan()`
+- **General** (`jsonBody`, `textBody`, `headers`): `.equals()`, `.notEquals()`, `.contains()`, `.notContains()`, `.greaterThan()`, `.lessThan()`, `.isEmpty()`, `.notEmpty()`, `.isNull()`, `.isNotNull()`, `.hasKey()`, `.notHasKey()`, `.hasValue()`, `.notHasValue()`
+
+Note the names: `notEmpty` (not `isNotEmpty`), `greaterThan` / `lessThan` (not `isGreaterThan` / `isLessThan`).
+
+#### Authentication Setup Scripts for API Checks
+
+- Setup scripts should be flat scripts, no functions, no exports, they will be executed straight by Checkly.
+- 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
+
+- Import the `BrowserCheck` construct from `checkly/constructs`.
+- Generate a separate `.spec.ts` file for the Playwright code referenced in the `BrowserCheck` construct.
+- 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/
+
+```typescript
+import { AlertEscalationBuilder, BrowserCheck, Frequency, RetryStrategyBuilder } from 'checkly/constructs'
+
+new BrowserCheck('example-browser-check', {
+  name: 'Example Browser Check',
+  code: {
+    entrypoint: './example-browser-check.spec.ts',
+  },
+  activated: false,
+  locations: [
+    'eu-central-1',
+    'eu-west-2',
+  ],
+  frequency: Frequency.EVERY_10M,
+  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
+    amount: 0,
+    interval: 5,
+  }, {
+    enabled: false,
+    percentage: 10,
+  }),
+  retryStrategy: RetryStrategyBuilder.noRetries(),
+  runParallel: true,
+})
+```
+
+### 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/
+
+```typescript
+import { PlaywrightCheck } from "checkly/constructs"
+
+const playwrightChecks = new PlaywrightCheck("multi-browser-check", {
+  name: "Multi-browser check suite",
+  playwrightConfigPath: "./playwright.config.ts",
+  // 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"],
+});
+```
+
+### MultiStep Checks
+
+- 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/
+
+```typescript
+import { AlertEscalationBuilder, Frequency, MultiStepCheck, RetryStrategyBuilder } from 'checkly/constructs'
+
+new MultiStepCheck('example-multi-step-check', {
+  name: 'Example Multistep Check',
+  code: {
+    entrypoint: './example-multistep-check.spec.ts',
+  },
+  activated: true,
+  locations: [
+    'eu-central-1',
+    'eu-west-2',
+  ],
+  frequency: Frequency.EVERY_1H,
+  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
+    amount: 0,
+    interval: 5,
+  }, {
+    enabled: false,
+    percentage: 10,
+  }),
+  retryStrategy: RetryStrategyBuilder.noRetries(),
+  runParallel: true,
+})
+```
+
+### TCP Monitor
+
+- Import the `TcpMonitor` construct from `checkly/constructs`.
+- When adding `assertions`, always use `TcpAssertionBuilder` class for TCP monitors.
+- **Plan-gated properties:** `retryStrategy`, `runParallel`, and higher frequencies are not available on all plans. Check entitlements matching `UPTIME_CHECKS_*` before using these. Omit any property whose entitlement is disabled. See `npx checkly skills manage` for details.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/tcp-monitor/
+
+```typescript
+import { AlertEscalationBuilder, Frequency, RetryStrategyBuilder, TcpAssertionBuilder, TcpMonitor } from 'checkly/constructs'
+
+new TcpMonitor('example-tcp-monitor', {
+  name: 'Example TCP Monitor',
+  degradedResponseTime: 5000,
+  maxResponseTime: 5000,
+  activated: true,
+  locations: [
+    'eu-central-1',
+    'eu-west-2',
+  ],
+  frequency: Frequency.EVERY_1H,
+  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
+    amount: 0,
+    interval: 5,
+  }, {
+    enabled: false,
+    percentage: 10,
+  }),
+  retryStrategy: RetryStrategyBuilder.noRetries(),
+  runParallel: true,
+  request: {
+    hostname: 'INSERT_HOSTNAME',
+    port: 4242,
+    ipFamily: 'IPv4',
+    assertions: [
+      TcpAssertionBuilder.responseTime().lessThan(200),
+      TcpAssertionBuilder.responseData().isEmpty(),
+    ],
+  },
+})
+```
+
+### URL Monitor
+
+- Import the `UrlMonitor` construct from `checkly/constructs`.
+- When adding `assertions`, always use `UrlAssertionBuilder`.
+- **Important:** The target URL must be publicly accessible — checks run on Checkly's cloud, not locally.
+- **Plan-gated properties:** `retryStrategy`, `runParallel`, and higher frequencies are not available on all plans. Check entitlements matching `UPTIME_CHECKS_*` before using these. Omit any property whose entitlement is disabled — Checkly applies safe defaults. See `npx checkly skills manage` for details.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/url-monitor/
+
+```typescript
+import { AlertEscalationBuilder, Frequency, RetryStrategyBuilder, UrlAssertionBuilder, UrlMonitor } from 'checkly/constructs'
+
+new UrlMonitor('example-url-monitor', {
+  name: 'Example URL Monitor',
+  activated: true,
+  locations: [
+    'eu-central-1',
+    'eu-west-2',
+  ],
+  frequency: Frequency.EVERY_5M,
+  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
+    amount: 0,
+    interval: 5,
+  }, {
+    enabled: false,
+    percentage: 10,
+  }),
+  retryStrategy: RetryStrategyBuilder.noRetries(),
+  runParallel: true,
+  degradedResponseTime: 5000,
+  maxResponseTime: 20000,
+  request: {
+    url: 'INSERT_URL',
+    ipFamily: 'IPv4',
+    assertions: [
+      UrlAssertionBuilder.statusCode().equals(200),
+    ],
+  },
+})
+```
+
+### DNS Monitor
+
+- Import the `DnsMonitor` construct from `checkly/constructs`.
+- Reference [the docs for DNS monitors](https://www.checklyhq.com/docs/constructs/dns-monitor/) before generating any code.
+- When adding `assertions`, always use `DnsAssertionBuilder` class.
+- **Plan-gated properties:** `retryStrategy`, `runParallel`, and higher frequencies are not available on all plans. Check entitlements matching `UPTIME_CHECKS_*` before using these. Omit any property whose entitlement is disabled. See `npx checkly skills manage` for details.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/dns-monitor/
+
+```typescript
+import { AlertEscalationBuilder, DnsAssertionBuilder, DnsMonitor, Frequency, RetryStrategyBuilder } from 'checkly/constructs'
+
+new DnsMonitor('example-dns-monitor', {
+  name: 'Example DNS Monitor',
+  degradedResponseTime: 500,
+  maxResponseTime: 1000,
+  activated: true,
+  locations: [
+    'eu-central-1',
+    'eu-north-1',
+  ],
+  frequency: Frequency.EVERY_10M,
+  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
+    amount: 0,
+    interval: 5,
+  }, {
+    enabled: false,
+    percentage: 10,
+  }),
+  retryStrategy: RetryStrategyBuilder.noRetries(),
+  request: {
+    recordType: 'AAAA',
+    query: 'INSERT_HOSTNAME',
+    assertions: [
+      DnsAssertionBuilder.responseCode().equals('NOERROR'),
+    ],
+  },
+})
+```
+
+### ICMP Monitor
+
+- Import the `IcmpMonitor` construct from `checkly/constructs`.
+- Reference [the docs for ICMP monitors](https://www.checklyhq.com/docs/constructs/icmp-monitor/) before generating any code.
+- When adding `assertions`, always use `IcmpAssertionBuilder` class.
+- Latency assertions require a property parameter: `'avg'`, `'min'`, `'max'`, or `'stdDev'`.
+- Use `degradedPacketLossThreshold` and `maxPacketLossThreshold` for packet loss thresholds (percentages).
+- **Plan-gated properties:** `retryStrategy`, `runParallel`, and higher frequencies are not available on all plans. Check entitlements matching `UPTIME_CHECKS_*` before using these. Omit any property whose entitlement is disabled. See `npx checkly skills manage` for details.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/icmp-monitor/
+
+```typescript
+import { AlertEscalationBuilder, Frequency, IcmpAssertionBuilder, IcmpMonitor, RetryStrategyBuilder } from 'checkly/constructs'
+
+new IcmpMonitor('example-icmp-monitor', {
+  name: 'Example ICMP Monitor',
+  request: {
+    hostname: 'INSERT_HOSTNAME',
+    pingCount: 10,
+    assertions: [
+      IcmpAssertionBuilder.latency('avg').lessThan(100),
+      IcmpAssertionBuilder.latency('max').lessThan(200),
+    ],
+  },
+  degradedPacketLossThreshold: 10,
+  maxPacketLossThreshold: 20,
+  activated: true,
+  locations: [
+    'eu-central-1',
+    'eu-north-1',
+  ],
+  frequency: Frequency.EVERY_10M,
+  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
+    amount: 0,
+    interval: 5,
+  }, {
+    enabled: false,
+    percentage: 10,
+  }),
+  retryStrategy: RetryStrategyBuilder.noRetries(),
+})
+```
+
+### Heartbeat Monitor
+
+- Import the `HeartbeatMonitor` construct from `checkly/constructs`.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/heartbeat-monitor/
+
+```typescript
+import { AlertEscalationBuilder, Frequency, HeartbeatMonitor, RetryStrategyBuilder } from 'checkly/constructs'
+
+new HeartbeatMonitor('example-heartbeat-monitor', {
+  name: 'Example Heartbeat Monitor',
+  period: 1,
+  periodUnit: 'hours',
+  grace: 30,
+  graceUnit: 'minutes',
+  activated: true,
+  frequency: Frequency.EVERY_10S,
+  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
+    amount: 0,
+    interval: 5,
+  }, {
+    enabled: false,
+    percentage: 10,
+  }),
+  retryStrategy: RetryStrategyBuilder.noRetries(),
+  runParallel: true,
+})
+```
+
+### Check Groups
+
+- 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/
+
+```typescript
+import { CheckGroupV2 } from 'checkly/constructs'
+
+export const exampleGroup = new CheckGroupV2('example-group', {
+  name: 'Example Group',
+})
+```
+
+### Alert Channels
+
+- Alert channels are used to send notifications when checks and monitors fail or recover.
+- Alert channels are added to checks, monitors, and check groups constructs by adding them to the `alertChannels` array property.
+
+Here are some examples of how to create different types of alert channels.
+
+All available alerts are described in the [Checkly docs](https://www.checklyhq.com/docs/constructs/overview/).
+
+*Important*: Don't make up email addresses, phone numbers, Slack channel names or similar static values. Scan the project to discover a valid configuration or ask what the values should be.
+
+For new Slack notifications, prefer `SlackAppAlertChannel`. It uses the Checkly Slack App and only needs Slack `#channel` names or `@user` handles in `slackChannels`.
+
+#### Email Alert Channel
+
+**Reference:** https://www.checklyhq.com/docs/constructs/email-alert-channel/
+
+```typescript
+import { EmailAlertChannel } from 'checkly/constructs'
+
+export const testEmailAlert = new EmailAlertChannel('example-email-alert-channel', {
+  address: 'test@example.com',
+  sslExpiry: true,
+})
+```
+
+#### Phone Call Alert Channel
+
+**Reference:** https://www.checklyhq.com/docs/constructs/phone-call-alert-channel/
+
+```typescript
+import { PhoneCallAlertChannel } from 'checkly/constructs'
+
+export const testUserPhoneCallAlert = new PhoneCallAlertChannel('example-call-alert-channel', {
+  name: 'Test User',
+  phoneNumber: 'INSERT_PHONE_NUMBER',
+})
+```
+
+#### Slack App Alert Channel
+
+**Reference:** https://www.checklyhq.com/docs/constructs/slack-app-alert-channel/
+
+```typescript
+import { SlackAppAlertChannel } from 'checkly/constructs'
+
+export const alertsOpsAliceSlackAppAlert = new SlackAppAlertChannel('example-slack-app-alert-channel', {
+  slackChannels: [
+    '#alerts',
+    '#ops',
+    '@alice',
+  ],
+})
+```
+
+### Supporting Constructs
+
+#### Status Page
+
+- Import the `StatusPage` construct from `checkly/constructs`.
+- Status pages are used to display the status of your services to your users.
+- A Status Page consists of cards which include Status Page Services.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/status-page/
+
+```typescript
+import { StatusPage } from 'checkly/constructs'
+import { exampleService } from './services/example-service.check'
+
+new StatusPage('example-status-page', {
+  name: 'Example Status Page',
+  url: 'example-status-page',
+  cards: [
+    {
+      name: 'Example service',
+      services: [
+        exampleService,
+      ],
+    },
+  ],
+  customDomain: 'status.example.com',
+  defaultTheme: 'AUTO',
+})
+```
+
+#### Status Page Service
+
+- Import the `StatusPageService` construct from `checkly/constructs`.
+- Status Page Services are used to represent individual services on a Status Page.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/status-page-service/
+
+```typescript
+import { StatusPageService } from 'checkly/constructs'
+
+export const exampleService = new StatusPageService('example-status-page-service', {
+  name: 'Example Service',
+})
+```
+
+#### Dashboard
+
+- Import the `Dashboard` construct from `checkly/constructs`.
+- Dashboards are used to display the results of your checks on screens external to Checkly.
+- To apply custom styling, set `customCSS` to an entrypoint object so Checkly bundles and hosts the file: `customCSS: { entrypoint: './dashboard.css' }`. Passing a raw string read with `fs.readFileSync` is rejected at deploy time.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/dashboard/
+
+```typescript
+import { Dashboard } from 'checkly/constructs'
+
+new Dashboard('example-dashboard', {
+  tags: [
+    'app:webshop',
+  ],
+  customUrl: 'example-dashboard',
+  customDomain: 'dash.example.com',
+  header: 'Example Dashboard',
+  description: 'Example dashboard',
+  width: 'FULL',
+  refreshRate: 60,
+  paginate: true,
+  paginationRate: 60,
+  checksPerPage: 15,
+  useTagsAndOperator: false,
+  hideTags: false,
+  enableIncidents: false,
+  expandChecks: false,
+  showHeader: true,
+  isPrivate: false,
+  showP95: true,
+  showP99: true,
+})
+```
+
+#### Maintenance Window
+
+- Import the `MaintenanceWindow` construct from `checkly/constructs`.
+- Maintenance windows are used to pause checks during maintenance periods so no alerts are sent.
+- Checks are referenced by their tags in the `tags` property.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/maintenance-window/
+
+```typescript
+import { MaintenanceWindow } from 'checkly/constructs'
+
+new MaintenanceWindow('example-maintenance-window', {
+  name: 'Example Maintenance Window',
+  tags: [
+    'app:webshop',
+  ],
+  startsAt: new Date('2025-07-01T09:00:00.000Z'),
+  endsAt: new Date('2025-07-01T10:00:00.000Z'),
+  repeatInterval: 1,
+  repeatUnit: 'WEEK',
+  repeatEndsAt: new Date('2025-08-01T00:00:00.000Z'),
+})
+```
+
+#### Private Location
+
+- Import the `PrivateLocation` construct from `checkly/constructs`.
+- Private locations are used to run checks from your own infrastructure with the Checkly Agent, an OCI compatible container.
+
+**Reference:** https://www.checklyhq.com/docs/constructs/private-location/
+
+```typescript
+import { PrivateLocation } from 'checkly/constructs'
+
+export const examplePrivateLocation = new PrivateLocation('example-private-location', {
+  name: 'Example Private Location',
+  slugName: 'example-private-location',
+  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.