checkly 0.0.0-canary.7b9cf29

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

@@ -0,0 +1,112 @@
+---
+name: checkly
+description: Set up, create, test and manage monitoring checks using the Checkly CLI. Use when working with Agentic Checks, API Checks, Browser Checks, URL Monitors, ICMP Monitors, Playwright Check Suites, Heartbeat Monitors, Alert Channels, Dashboards, or Status Pages. Access Checkly account plan, entitlements, feature limits, members, and pending invites. Includes generic API pass-through (`checkly api`) for endpoints without dedicated commands.
+allowed-tools: Bash(npx:checkly:*) Bash(npm:install:*)
+metadata:
+  author: checkly
+---
+
+# Checkly
+
+**Required:** Before answering any Checkly question, run `npx checkly skills` to get the current and up-to-date action list. Do not rely on memory or prior context — the CLI is the source of truth and actions might change between releases.
+
+Then run `npx checkly skills <action>` to load up-to-date details for the action you need.
+
+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:
+
+1. **Metadata** (~80 tokens): Name and description in frontmatter
+2. **Core Instructions** (~1K tokens): Main SKILL.md content with links to reference commands
+3. **Reference Commands** (loaded on demand): Detailed construct documentation with examples
+
+Agents load what they need for each task.
+
+## Plan Awareness
+
+Before configuring checks, run `npx checkly account plan --output json` to see what features, locations, and limits are available on the current plan. Disabled features include an `upgradeUrl` pointing to the self-service checkout page or the enterprise contact sales page — share these with the user when they need a feature that's not on their plan.
+
+Run `npx checkly skills manage` for the full reference.
+
+## Confirmation Protocol
+
+Write commands (e.g. `incidents create`, `deploy`, `destroy`) return exit code 2 with a `confirmation_required` JSON envelope instead of executing. **Always present the `changes` to the user and wait for approval before running the `confirmCommand`.** Never auto-append `--force`. This applies to every write command individually — updates and resolutions need confirmation too, not just the initial create.
+
+Run `npx checkly skills communicate` for the full protocol details.
+
+## API Pass-Through (fallback for any endpoint)
+
+When no dedicated CLI command exists for an endpoint, use `npx checkly api` to make authenticated requests directly. The CLI handles auth headers and base URL automatically.
+
+```bash
+npx checkly api /v1/checks
+npx checkly api /v1/dashboards -X GET --jq '.[].name'
+npx checkly api /v1/checks -X POST -F name=MyCheck -F activated:=true
+npx checkly api /v1/checks -X GET -F limit=5
+```
+
+Key flags: `-X` (method), `-F` (field — `key=value` for strings, `key:=value` for JSON), `-H` (header), `--jq` (filter with jq), `--input` (body from file/stdin), `-i` / `--include` (response status + headers on stdout), `--verbose` (request/response headers on stderr).
+
+### Nested payloads
+
+Use `:=` to send structured JSON in a single field:
+
+```bash
+npx checkly api /v1/checks/<id> -X PATCH \
+  -F retryStrategy:='{"type":"LINEAR","maxRetries":2,"baseBackoffSeconds":10}'
+```
+
+For large or deeply nested bodies, pipe a JSON file via `--input`:
+
+```bash
+npx checkly api /v1/checks -X POST --input ./new-check.json
+```
+
+### Pagination
+
+`checkly api` does not auto-walk pages. Drive pagination yourself, the same way every other `checkly` list command exposes it.
+
+When using `-F` on a read endpoint, **always pass `-X GET` explicitly** — any `-F` flag implies POST unless the method is set, so omitting `-X GET` will try to create a resource with your pagination params as the body.
+
+**Detecting which pagination style an endpoint uses.** Make a first request with `-i` (response headers on stdout) and inspect what came back:
+
+- **Page-based** → response has a `content-range` header (e.g. `0-1/23` means items 0–1 of 23 total) and usually a `link` header with `rel="next"` / `rel="last"`. The body is a bare array. Walk by incrementing `-F page=N` until you've covered the total in `content-range`, or until the `rel="next"` link disappears.
+- **Cursor-based** → response body is an envelope like `{ entries: [...], nextId: "...", length: N }`. Pass `-F nextId=<value>` (or `-F cursor=<value>`, depending on the endpoint) on the next call. When `nextId` is missing or null, you've reached the end.
+
+```bash
+# Step 1: make the first call with -i and inspect the response shape
+npx checkly api /v1/checks -X GET -F limit=100 -i
+
+# If you saw a content-range header → page-based, walk with -F page=N
+npx checkly api /v1/checks -X GET -F limit=100 -F page=2 -i
+
+# If the body had a nextId field → cursor-based, walk with -F nextId=<value>
+npx checkly api /v1/status-pages -X GET -F limit=50 -F nextId=<nextIdFromPrevResponse>
+```
+
+### Error responses
+
+On non-2xx, the response body is still written to stdout (read it for the API's error message) and the CLI exits with code 1. A 401 prints an auth hint, a 403 prints a permission hint, and a 404 prints the docs URL — all on stderr.
+
+### Endpoint discovery
+
+See the [Checkly API reference](https://www.checklyhq.com/docs/api) for the human-readable endpoint catalogue, or fetch the [OpenAPI spec](https://api.checklyhq.com/openapi.json) for a machine-readable definition you can grep for paths, parameters, and response shapes.
+
+### `npx checkly skills initialize`
+Learn how to initialize and set up a new Checkly CLI project from scratch.
+
+### `npx checkly skills configure`
+Learn how to create and manage monitoring checks using Checkly constructs and the CLI.
+
+### `npx checkly skills investigate`
+Access check and test-session status, analyze failures, inspect attempts/assets, and investigate errors.
+
+### `npx checkly skills communicate`
+Open incidents and lead customer communications via status pages.
+
+### `npx checkly skills manage`
+Understand your account plan, entitlements, feature limits, members, and pending invites.

package/dist/ai-context/skills-command/references/communicate-incidents.md

@@ -0,0 +1,79 @@
+# Communicate Incidents
+
+Create, update, and resolve incidents on status pages. All write commands require confirmation (see `npx checkly skills communicate` for the confirmation protocol).
+
+## List incidents
+
+```bash
+npx checkly incidents list
+npx checkly incidents list --status active --output json
+npx checkly incidents list --status resolved --limit 5
+```
+
+Flags:
+- `--status <status>` — `active` (default), `resolved`, or `all`
+- `--limit <n>` — max incidents to return
+- `-o, --output <format>` — `table` (default), `json`, or `md`
+
+## Create an incident
+
+```bash
+npx checkly incidents create \
+  --status-page-id <id> \
+  --title "Service degradation" \
+  --severity major \
+  --message "Investigating elevated error rates" \
+  --services <service-id-1> --services <service-id-2>
+```
+
+Flags:
+- `--status-page-id <id>` — **(required)** target status page
+- `--title <text>` — **(required)** incident title
+- `--severity <level>` — `minor` (default), `medium`, `major`, or `critical`
+- `--message <text>` — initial update message
+- `--services <id>` — affected service IDs (repeat for multiple)
+- `--[no-]notify-subscribers` — notify status page subscribers (default: true)
+- `--force` — skip confirmation (required for non-interactive execution after user approval)
+- `--dry-run` — preview without executing
+
+## Update an incident
+
+```bash
+npx checkly incidents update <incident-id> \
+  --message "Root cause identified" \
+  --status identified
+```
+
+Flags:
+- `--message <text>` — **(required)** update message
+- `--status <status>` — `investigating`, `identified`, `monitoring`, or `fixing`
+- `--severity <level>` — update severity
+- `--[no-]notify-subscribers` — notify subscribers
+- `--force` — skip confirmation
+- `--dry-run` — preview without executing
+
+## Resolve an incident
+
+```bash
+npx checkly incidents resolve <incident-id> \
+  --message "Issue resolved, monitoring confirms recovery"
+```
+
+Flags:
+- `--message <text>` — resolution message
+- `--[no-]notify-subscribers` — notify subscribers
+- `--force` — skip confirmation
+- `--dry-run` — preview without executing
+
+## Status pages
+
+Use `npx checkly status-pages list` to find status page IDs, and `npx checkly status-pages get` for full details including cards and services.
+
+```bash
+npx checkly status-pages list
+npx checkly status-pages list --output json
+npx checkly status-pages get <status-page-id>
+npx checkly status-pages get <status-page-id> --output json
+```
+
+Use `--output json` to get machine-readable service IDs for incident creation.

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

@@ -0,0 +1,33 @@
+# Customer Communications and Incident Management
+
+Open incidents and lead customer communications via status pages.
+
+## Confirmation Protocol
+
+Write commands (`incidents create`, `incidents update`, `incidents resolve`, `deploy`, `destroy`) require confirmation before executing. When the CLI detects an agent environment, it returns a JSON envelope with exit code 2 instead of executing:
+
+```json
+{
+  "status": "confirmation_required",
+  "command": "incidents create",
+  "description": "Create incident on status page",
+  "classification": { "readOnly": false, "destructive": false, "idempotent": false },
+  "changes": ["Will create incident \"DB outage\" on status page \"Acme\"", "Severity: major"],
+  "confirmCommand": "checkly incidents create --title=\"DB outage\" --status-page-id=\"sp-1\" --severity=\"major\" --force"
+}
+```
+
+**Rules for agents:**
+
+1. When exit code is 2 and output contains `"status": "confirmation_required"`, **always present the `changes` array to the user** and ask for confirmation.
+2. **Never auto-append `--force`** — only run the `confirmCommand` after the user explicitly approves.
+3. This applies to **every** write command, not just the first one. Incident updates and resolutions also require confirmation.
+4. Use `--dry-run` to preview what a command will do without executing or prompting.
+5. Read-only commands (`incidents list`, `status-pages list`) execute immediately without confirmation.
+
+## Available Commands
+
+Parse and read further reference documentation when tasked with any of the following:
+
+### `npx checkly skills communicate incidents`
+Incident lifecycle (`incidents create`, `update`, `resolve`, `list`) and status pages

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

@@ -0,0 +1,65 @@
+# 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,
+  }),
+})
+```

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

@@ -0,0 +1,54 @@
+# 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',
+  ],
+})
+```

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

@@ -0,0 +1,73 @@
+# 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.

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

@@ -0,0 +1,36 @@
+# 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,
+})
+```

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

@@ -0,0 +1,16 @@
+# 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',
+})
+```

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

@@ -0,0 +1,39 @@
+# 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'),
+    ],
+  },
+})
+```

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-heartbeat-monitors.md

@@ -0,0 +1,28 @@
+# 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,
+})
+```