From 7832f27d7f3586daa96259f2c2b51365a4d67f65 Mon Sep 17 00:00:00 2001
From: Simo Kinnunen <simo@checklyhq.com>
Date: Fri, 4 Sep 2026 21:07:18 +0900
Subject: [PATCH 1/8] fix(docs): correct non-compiling CLI samples on the
 dynamic monitor and uptime guides [RED-935]

Reported in checkly/checkly-cli#1457. The ApiCheck samples used `skipSsl`
(the property is `skipSSL`) and referenced `AssertionBuilder` without
importing it; the group sample set `maxResponseTime`, which CheckGroupV2
does not accept; and the URL monitor sample used the non-existent
`Frequency.EVERY_60S`.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 constructs/dynamic-monitor-creation.mdx | 8 ++++----
 guides/create-multiple-monitors.mdx     | 5 +++--
 guides/uptime-monitoring.mdx            | 2 +-
 3 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/constructs/dynamic-monitor-creation.mdx b/constructs/dynamic-monitor-creation.mdx
index 8888dae6..f9843602 100644
--- a/constructs/dynamic-monitor-creation.mdx
+++ b/constructs/dynamic-monitor-creation.mdx
@@ -14,7 +14,7 @@ This page shows a few examples.
 Iterating through lists of target URLs is an easy way to manage checks at scale while avoiding code duplication.
 
 ```ts __checks__/api.check.ts
-import { ApiCheck } from 'checkly/constructs'
+import { ApiCheck, AssertionBuilder } from 'checkly/constructs'
 
 const publicResources = ['/public-stats', '/v1/runtimes']
 
@@ -25,7 +25,7 @@ for (const publicResource of publicResources) {
       url: `https://api.checkly.com${publicResource}`,
       method: 'GET',
       followRedirects: true,
-      skipSsl: false,
+      skipSSL: false,
       assertions: [ AssertionBuilder.statusCode().equals(200) ]
     }
   })
@@ -35,7 +35,7 @@ for (const publicResource of publicResources) {
 Asynchronous operations are supported by exporting an async function from your check files, too.
 
 ```ts __checks__/api.check.ts
-import { ApiCheck } from 'checkly/constructs'
+import { ApiCheck, AssertionBuilder } from 'checkly/constructs'
 import { getPublicResources } from './helpers'
 
 // an exported async function to signal that
@@ -50,7 +50,7 @@ export default async function createApiChecks() {
         url: `https://api.checkly.com${publicResource}`,
         method: 'GET',
         followRedirects: true,
-        skipSsl: false,
+        skipSSL: false,
         assertions: [ AssertionBuilder.statusCode().equals(200) ]
       }
     })
diff --git a/guides/create-multiple-monitors.mdx b/guides/create-multiple-monitors.mdx
index 101b08bd..5d6e47a0 100644
--- a/guides/create-multiple-monitors.mdx
+++ b/guides/create-multiple-monitors.mdx
@@ -248,7 +248,6 @@ export const prodMonitorGroup = new CheckGroupV2('prod-monitor-group', {
   name: 'Prod Monitor Group',
   activated: true,
   frequency: 5,
-  maxResponseTime: 10000,
   locations: ['us-east-1', 'eu-west-1'],
   tags: ['url-monitoring', 'production'],
   environmentVariables: [],
@@ -272,7 +271,9 @@ import { prodMonitorGroup } from './prod-monitoring-group.ts'
 new UrlMonitor('url-monitor-example', { 
   name: 'Example URL Monitor',
   group: prodMonitorGroup, //add this check to the group
-  //most config can now be handled at the group level
+  //most config can now be handled at the group level;
+  //response time thresholds are always set per monitor
+  maxResponseTime: 10000,
   request: {
     url: 'https://httpbin.org/get', 
     followRedirects: false, 
diff --git a/guides/uptime-monitoring.mdx b/guides/uptime-monitoring.mdx
index 871cfe65..bcb35612 100644
--- a/guides/uptime-monitoring.mdx
+++ b/guides/uptime-monitoring.mdx
@@ -31,7 +31,7 @@ It’s easy to create a URL Monitor from your IDE with Checkly CLI, just create
 import { Frequency, UrlMonitor, UrlAssertionBuilder } from 'checkly/constructs'
 
 new UrlMonitor('url-pinger-1', {
-  frequency: Frequency.EVERY_60S,
+  frequency: Frequency.EVERY_1M,
   name: 'URL pinger 1',
   activated: true,
   request: {

From ea8042719349eb698757945a734b888e0ab77de3 Mon Sep 17 00:00:00 2001
From: Simo Kinnunen <simo@checklyhq.com>
Date: Fri, 4 Sep 2026 21:15:13 +0900
Subject: [PATCH 2/8] fix(docs): rewrite the uptime CLI configuration samples
 to real construct APIs [RED-935]

The samples on detect/uptime-monitoring/cli-configuration.mdx used
properties and classes that do not exist in the checkly package:
`method`/`headers` on URL monitor requests, `UrlAssertionBuilder`
response-time and body assertions, `target`/`timeout`/`ssl`/
`responseValidation` on TCP monitors, heartbeat monitors without
`periodUnit`/`graceUnit`, a `MonitorGroup` class, and alert channels
referenced by string name. Rewrite every ts/js sample pair to the real
API, retitle the two sections whose feature no longer applies, name the
check files so the default `checkMatch` picks them up, and bump the CI
workflow sample to a Node version the current CLI supports.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../uptime-monitoring/cli-configuration.mdx   | 240 ++++++++++--------
 1 file changed, 128 insertions(+), 112 deletions(-)

diff --git a/detect/uptime-monitoring/cli-configuration.mdx b/detect/uptime-monitoring/cli-configuration.mdx
index ad71d759..ec8115ae 100644
--- a/detect/uptime-monitoring/cli-configuration.mdx
+++ b/detect/uptime-monitoring/cli-configuration.mdx
@@ -41,13 +41,11 @@ new UrlMonitor('homepage-check', {
   activated: true,
   locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],
   frequency: 5, // minutes
+  maxResponseTime: 2000, // ms
   request: {
-    method: 'GET',
     url: 'https://www.myapp.com',
     assertions: [
       UrlAssertionBuilder.statusCode().equals(200),
-      UrlAssertionBuilder.responseTime().lessThan(2000),
-      UrlAssertionBuilder.body().contains('Welcome to MyApp'),
     ]
   },
   tags: ['production', 'frontend', 'critical']
@@ -62,13 +60,11 @@ new UrlMonitor('homepage-check', {
   activated: true,
   locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],
   frequency: 5, // minutes
+  maxResponseTime: 2000, // ms
   request: {
-    method: 'GET',
     url: 'https://www.myapp.com',
     assertions: [
       UrlAssertionBuilder.statusCode().equals(200),
-      UrlAssertionBuilder.responseTime().lessThan(2000),
-      UrlAssertionBuilder.body().contains('Welcome to MyApp'),
     ]
   },
   tags: ['production', 'frontend', 'critical']
@@ -77,62 +73,68 @@ new UrlMonitor('homepage-check', {
 
 </CodeGroup>
 
-### Advanced URL Monitor with Authentication
+### Advanced URL Monitor with Response Time Limits
+
+URL monitors only assert on the HTTP status code. If you need to send custom headers or assert on the response body, use an [API check](/detect/synthetic-monitoring/api-checks/overview) instead.
+
+The samples on this page define their alert channels inline to stay self-contained. In a real project, define each [alert channel](/constructs/alert-channel) once in a shared file, export it, and import it where needed; a logical ID may only be used once per project.
 
 <CodeGroup dropdown>
 
 ```ts api-monitor.check.ts
-import { UrlMonitor, UrlAssertionBuilder } from 'checkly/constructs'
+import { UrlMonitor, UrlAssertionBuilder, EmailAlertChannel, SlackAlertChannel } from 'checkly/constructs'
+
+const emailAlerts = new EmailAlertChannel('email-alerts', {
+  address: 'ops@myapp.com'
+})
+const slackAlerts = new SlackAlertChannel('slack-alerts', {
+  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
+  channel: '#alerts'
+})
 
 new UrlMonitor('api-health-check', {
   name: 'API Health Check',
   activated: true,
   locations: ['us-east-1', 'eu-west-1'],
   frequency: 2, // minutes
+  degradedResponseTime: 500, // ms
+  maxResponseTime: 1000, // ms
   request: {
-    method: 'GET',
     url: 'https://api.myapp.com/health',
-    headers: {
-      'Authorization': 'Bearer {{API_TOKEN}}',
-      'Content-Type': 'application/json',
-      'User-Agent': 'Checkly Monitor'
-    },
     assertions: [
       UrlAssertionBuilder.statusCode().equals(200),
-      UrlAssertionBuilder.responseTime().lessThan(1000),
-      UrlAssertionBuilder.jsonBody('$.status').equals('healthy'),
-      UrlAssertionBuilder.jsonBody('$.version').exists(),
     ]
   },
-  alertChannels: ['email-alerts', 'slack-alerts'],
+  alertChannels: [emailAlerts, slackAlerts],
   tags: ['production', 'api', 'critical']
 })
 ```
 
 ```js api-monitor.check.js
-const { UrlMonitor, UrlAssertionBuilder } = require('checkly/constructs')
+const { UrlMonitor, UrlAssertionBuilder, EmailAlertChannel, SlackAlertChannel } = require('checkly/constructs')
+
+const emailAlerts = new EmailAlertChannel('email-alerts', {
+  address: 'ops@myapp.com'
+})
+const slackAlerts = new SlackAlertChannel('slack-alerts', {
+  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
+  channel: '#alerts'
+})
 
 new UrlMonitor('api-health-check', {
   name: 'API Health Check',
   activated: true,
   locations: ['us-east-1', 'eu-west-1'],
   frequency: 2, // minutes
+  degradedResponseTime: 500, // ms
+  maxResponseTime: 1000, // ms
   request: {
-    method: 'GET',
     url: 'https://api.myapp.com/health',
-    headers: {
-      'Authorization': 'Bearer {{API_TOKEN}}',
-      'Content-Type': 'application/json',
-      'User-Agent': 'Checkly Monitor'
-    },
     assertions: [
       UrlAssertionBuilder.statusCode().equals(200),
-      UrlAssertionBuilder.responseTime().lessThan(1000),
-      UrlAssertionBuilder.jsonBody('$.status').equals('healthy'),
-      UrlAssertionBuilder.jsonBody('$.version').exists(),
     ]
   },
-  alertChannels: ['email-alerts', 'slack-alerts'],
+  alertChannels: [emailAlerts, slackAlerts],
   tags: ['production', 'api', 'critical']
 })
 ```
@@ -153,11 +155,11 @@ new TcpMonitor('database-tcp-check', {
   activated: true,
   locations: ['us-east-1', 'eu-west-1'],
   frequency: 5, // minutes
-  target: {
-    host: 'db.myapp.com',
+  degradedResponseTime: 3000, // ms
+  request: {
+    hostname: 'db.myapp.com',
     port: 5432
   },
-  timeout: 10, // seconds
   tags: ['production', 'database', 'infrastructure']
 })
 ```
@@ -170,60 +172,58 @@ new TcpMonitor('database-tcp-check', {
   activated: true,
   locations: ['us-east-1', 'eu-west-1'],
   frequency: 5, // minutes
-  target: {
-    host: 'db.myapp.com',
+  degradedResponseTime: 3000, // ms
+  request: {
+    hostname: 'db.myapp.com',
     port: 5432
   },
-  timeout: 10, // seconds
   tags: ['production', 'database', 'infrastructure']
 })
 ```
 
 </CodeGroup>
 
-### TCP Monitor with SSL and Response Validation
+### TCP Monitor with Response Validation
 
 <CodeGroup dropdown>
 
 ```ts mail-server-monitor.check.ts
-import { TcpMonitor } from 'checkly/constructs'
+import { TcpMonitor, TcpAssertionBuilder } from 'checkly/constructs'
 
 new TcpMonitor('mail-server-check', {
   name: 'SMTP Server Monitoring',
   activated: true,
   locations: ['us-east-1', 'eu-west-1'],
   frequency: 10, // minutes
-  target: {
-    host: 'mail.myapp.com',
+  degradedResponseTime: 3000, // ms
+  request: {
+    hostname: 'mail.myapp.com',
     port: 587,
-    ssl: true
-  },
-  timeout: 15, // seconds
-  responseValidation: {
-    expectedResponse: '220',
-    timeout: 5
+    assertions: [
+      // The SMTP server greets with a "220" banner on connect
+      TcpAssertionBuilder.responseData().contains('220'),
+    ]
   },
   tags: ['production', 'mail', 'infrastructure']
 })
 ```
 
 ```js mail-server-monitor.check.js
-const { TcpMonitor } = require('checkly/constructs')
+const { TcpMonitor, TcpAssertionBuilder } = require('checkly/constructs')
 
 new TcpMonitor('mail-server-check', {
   name: 'SMTP Server Monitoring',
   activated: true,
   locations: ['us-east-1', 'eu-west-1'],
   frequency: 10, // minutes
-  target: {
-    host: 'mail.myapp.com',
+  degradedResponseTime: 3000, // ms
+  request: {
+    hostname: 'mail.myapp.com',
     port: 587,
-    ssl: true
-  },
-  timeout: 15, // seconds
-  responseValidation: {
-    expectedResponse: '220',
-    timeout: 5
+    assertions: [
+      // The SMTP server greets with a "220" banner on connect
+      TcpAssertionBuilder.responseData().contains('220'),
+    ]
   },
   tags: ['production', 'mail', 'infrastructure']
 })
@@ -243,8 +243,10 @@ import { HeartbeatMonitor } from 'checkly/constructs'
 new HeartbeatMonitor('daily-backup-heartbeat', {
   name: 'Daily Database Backup',
   activated: true,
-  period: 24 * 60, // 24 hours in minutes
+  period: 24,
+  periodUnit: 'hours',
   grace: 30, // 30 minutes grace period
+  graceUnit: 'minutes',
   tags: ['backup', 'database', 'daily']
 })
 ```
@@ -255,8 +257,10 @@ const { HeartbeatMonitor } = require('checkly/constructs')
 new HeartbeatMonitor('daily-backup-heartbeat', {
   name: 'Daily Database Backup',
   activated: true,
-  period: 24 * 60, // 24 hours in minutes
+  period: 24,
+  periodUnit: 'hours',
   grace: 30, // 30 minutes grace period
+  graceUnit: 'minutes',
   tags: ['backup', 'database', 'daily']
 })
 ```
@@ -268,27 +272,49 @@ new HeartbeatMonitor('daily-backup-heartbeat', {
 <CodeGroup dropdown>
 
 ```ts sync-job-heartbeat.check.ts
-import { HeartbeatMonitor } from 'checkly/constructs'
+import { HeartbeatMonitor, PagerdutyAlertChannel, SlackAlertChannel } from 'checkly/constructs'
+
+const pagerdutyCritical = new PagerdutyAlertChannel('pagerduty-critical', {
+  serviceName: 'Data platform',
+  serviceKey: 'your-pagerduty-integration-key'
+})
+const slackOps = new SlackAlertChannel('slack-ops', {
+  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
+  channel: '#ops'
+})
 
 new HeartbeatMonitor('hourly-sync-heartbeat', {
   name: 'Hourly Data Sync Job',
   activated: true,
-  period: 60, // 1 hour in minutes
+  period: 1,
+  periodUnit: 'hours',
   grace: 10, // 10 minutes grace period
-  alertChannels: ['pagerduty-critical', 'slack-ops'],
+  graceUnit: 'minutes',
+  alertChannels: [pagerdutyCritical, slackOps],
   tags: ['sync', 'data', 'hourly', 'critical']
 })
 ```
 
 ```js sync-job-heartbeat.check.js
-const { HeartbeatMonitor } = require('checkly/constructs')
+const { HeartbeatMonitor, PagerdutyAlertChannel, SlackAlertChannel } = require('checkly/constructs')
+
+const pagerdutyCritical = new PagerdutyAlertChannel('pagerduty-critical', {
+  serviceName: 'Data platform',
+  serviceKey: 'your-pagerduty-integration-key'
+})
+const slackOps = new SlackAlertChannel('slack-ops', {
+  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
+  channel: '#ops'
+})
 
 new HeartbeatMonitor('hourly-sync-heartbeat', {
   name: 'Hourly Data Sync Job',
   activated: true,
-  period: 60, // 1 hour in minutes
+  period: 1,
+  periodUnit: 'hours',
   grace: 10, // 10 minutes grace period
-  alertChannels: ['pagerduty-critical', 'slack-ops'],
+  graceUnit: 'minutes',
+  alertChannels: [pagerdutyCritical, slackOps],
   tags: ['sync', 'data', 'hourly', 'critical']
 })
 ```
@@ -303,15 +329,23 @@ Organize related monitors using groups:
 
 <CodeGroup dropdown>
 
-```ts api-monitoring-group.ts
-import { MonitorGroup } from 'checkly/constructs'
+```ts api-monitoring-group.check.ts
+import { CheckGroupV2, UrlMonitor, EmailAlertChannel, SlackAlertChannel } from 'checkly/constructs'
+
+const emailAlerts = new EmailAlertChannel('email-alerts', {
+  address: 'ops@myapp.com'
+})
+const slackApiAlerts = new SlackAlertChannel('slack-api-alerts', {
+  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
+  channel: '#api-alerts'
+})
 
-const apiGroup = new MonitorGroup('api-monitoring', {
+const apiGroup = new CheckGroupV2('api-monitoring', {
   name: 'API Monitoring',
   activated: true,
   locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],
   frequency: 5,
-  alertChannels: ['email-alerts', 'slack-api-alerts'],
+  alertChannels: [emailAlerts, slackApiAlerts],
   tags: ['api', 'production']
 })
 
@@ -320,8 +354,7 @@ new UrlMonitor('users-api', {
   name: 'Users API',
   group: apiGroup,
   request: {
-    url: 'https://api.myapp.com/users',
-    method: 'GET'
+    url: 'https://api.myapp.com/users'
   }
 })
 
@@ -329,21 +362,28 @@ new UrlMonitor('orders-api', {
   name: 'Orders API',
   group: apiGroup,
   request: {
-    url: 'https://api.myapp.com/orders',
-    method: 'GET'
+    url: 'https://api.myapp.com/orders'
   }
 })
 ```
 
-```js api-monitoring-group.js
-const { MonitorGroup, UrlMonitor } = require('checkly/constructs')
+```js api-monitoring-group.check.js
+const { CheckGroupV2, UrlMonitor, EmailAlertChannel, SlackAlertChannel } = require('checkly/constructs')
 
-const apiGroup = new MonitorGroup('api-monitoring', {
+const emailAlerts = new EmailAlertChannel('email-alerts', {
+  address: 'ops@myapp.com'
+})
+const slackApiAlerts = new SlackAlertChannel('slack-api-alerts', {
+  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
+  channel: '#api-alerts'
+})
+
+const apiGroup = new CheckGroupV2('api-monitoring', {
   name: 'API Monitoring',
   activated: true,
   locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],
   frequency: 5,
-  alertChannels: ['email-alerts', 'slack-api-alerts'],
+  alertChannels: [emailAlerts, slackApiAlerts],
   tags: ['api', 'production']
 })
 
@@ -352,8 +392,7 @@ new UrlMonitor('users-api', {
   name: 'Users API',
   group: apiGroup,
   request: {
-    url: 'https://api.myapp.com/users',
-    method: 'GET'
+    url: 'https://api.myapp.com/users'
   }
 })
 
@@ -361,21 +400,20 @@ new UrlMonitor('orders-api', {
   name: 'Orders API',
   group: apiGroup,
   request: {
-    url: 'https://api.myapp.com/orders',
-    method: 'GET'
+    url: 'https://api.myapp.com/orders'
   }
 })
 ```
 
 </CodeGroup>
 
-### Environment Variables and Secrets
+### Environment Variables
 
-Use environment variables for configuration:
+Use environment variables to vary the configuration per environment:
 
 <CodeGroup dropdown>
 
-```ts environment-config.ts
+```ts environment-config.check.ts
 import { UrlMonitor, UrlAssertionBuilder } from 'checkly/constructs'
 
 // Environment-specific configuration
@@ -389,23 +427,18 @@ new UrlMonitor(`${environment}-api-check`, {
     ? ['us-east-1', 'eu-west-1', 'ap-southeast-1']
     : ['us-east-1'],
   frequency: environment === 'production' ? 2 : 10,
+  maxResponseTime: environment === 'production' ? 2000 : 5000, // ms
   request: {
-    method: 'GET',
     url: `${baseUrl}/health`,
-    headers: {
-      'Authorization': 'Bearer {{API_TOKEN}}',
-      'X-Environment': environment
-    },
     assertions: [
       UrlAssertionBuilder.statusCode().equals(200),
-      UrlAssertionBuilder.jsonBody('$.environment').equals(environment),
     ]
   },
   tags: [environment, 'api', 'health']
 })
 ```
 
-```js environment-config.js
+```js environment-config.check.js
 const { UrlMonitor, UrlAssertionBuilder } = require('checkly/constructs')
 
 // Environment-specific configuration
@@ -419,16 +452,11 @@ new UrlMonitor(`${environment}-api-check`, {
     ? ['us-east-1', 'eu-west-1', 'ap-southeast-1']
     : ['us-east-1'],
   frequency: environment === 'production' ? 2 : 10,
+  maxResponseTime: environment === 'production' ? 2000 : 5000, // ms
   request: {
-    method: 'GET',
     url: `${baseUrl}/health`,
-    headers: {
-      'Authorization': 'Bearer {{API_TOKEN}}',
-      'X-Environment': environment
-    },
     assertions: [
       UrlAssertionBuilder.statusCode().equals(200),
-      UrlAssertionBuilder.jsonBody('$.environment').equals(environment),
     ]
   },
   tags: [environment, 'api', 'health']
@@ -478,7 +506,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
 
       - name: Install dependencies
@@ -507,7 +535,7 @@ Generate monitors programmatically:
 
 <CodeGroup dropdown>
 
-```ts dynamic-monitors.ts
+```ts dynamic-monitors.check.ts
 import { UrlMonitor, UrlAssertionBuilder } from 'checkly/constructs'
 
 // Monitor multiple API endpoints
@@ -524,14 +552,11 @@ endpoints.forEach((endpoint, index) => {
     activated: true,
     locations: ['us-east-1', 'eu-west-1'],
     frequency: endpoint.path === '/payments' ? 1 : 5, // More frequent for critical endpoints
+    maxResponseTime: endpoint.path === '/payments' ? 500 : 1000, // Stricter limit for critical endpoints
     request: {
-      method: 'GET',
       url: `https://api.myapp.com${endpoint.path}`,
       assertions: [
         UrlAssertionBuilder.statusCode().equals(200),
-        UrlAssertionBuilder.responseTime().lessThan(
-          endpoint.path === '/payments' ? 500 : 1000
-        ),
       ]
     },
     tags: ['api', 'production', endpoint.path.replace('/', '')]
@@ -539,7 +564,7 @@ endpoints.forEach((endpoint, index) => {
 })
 ```
 
-```js dynamic-monitors.js
+```js dynamic-monitors.check.js
 const { UrlMonitor, UrlAssertionBuilder } = require('checkly/constructs')
 
 // Monitor multiple API endpoints
@@ -556,14 +581,11 @@ endpoints.forEach((endpoint, index) => {
     activated: true,
     locations: ['us-east-1', 'eu-west-1'],
     frequency: endpoint.path === '/payments' ? 1 : 5, // More frequent for critical endpoints
+    maxResponseTime: endpoint.path === '/payments' ? 500 : 1000, // Stricter limit for critical endpoints
     request: {
-      method: 'GET',
       url: `https://api.myapp.com${endpoint.path}`,
       assertions: [
         UrlAssertionBuilder.statusCode().equals(200),
-        UrlAssertionBuilder.responseTime().lessThan(
-          endpoint.path === '/payments' ? 500 : 1000
-        ),
       ]
     },
     tags: ['api', 'production', endpoint.path.replace('/', '')]
@@ -583,7 +605,6 @@ Centralized configuration management:
 interface MonitoringConfig {
   baseUrl: string
   locations: string[]
-  alertChannels: string[]
   defaultFrequency: number
   environment: string
 }
@@ -593,9 +614,6 @@ export const config: MonitoringConfig = {
   locations: process.env.ENVIRONMENT === 'production'
     ? ['us-east-1', 'eu-west-1', 'ap-southeast-1']
     : ['us-east-1'],
-  alertChannels: process.env.ENVIRONMENT === 'production'
-    ? ['email-alerts', 'slack-alerts', 'pagerduty']
-    : ['email-alerts'],
   defaultFrequency: process.env.ENVIRONMENT === 'production' ? 5 : 15,
   environment: process.env.ENVIRONMENT || 'development'
 }
@@ -607,9 +625,6 @@ const config = {
   locations: process.env.ENVIRONMENT === 'production'
     ? ['us-east-1', 'eu-west-1', 'ap-southeast-1']
     : ['us-east-1'],
-  alertChannels: process.env.ENVIRONMENT === 'production'
-    ? ['email-alerts', 'slack-alerts', 'pagerduty']
-    : ['email-alerts'],
   defaultFrequency: process.env.ENVIRONMENT === 'production' ? 5 : 15,
   environment: process.env.ENVIRONMENT || 'development'
 }
@@ -639,6 +654,7 @@ monitoring/
 ├── groups/
 │   ├── api-group.ts
 │   └── infrastructure-group.ts
+├── alert-channels.ts
 └── checkly.config.ts
 ```
 

From 06e5a77504082557e5284fb9453d494c481a814d Mon Sep 17 00:00:00 2001
From: Simo Kinnunen <simo@checklyhq.com>
Date: Fri, 4 Sep 2026 21:20:04 +0900
Subject: [PATCH 3/8] fix(docs): correct the remaining CLI samples that use a
 wrong construct API [RED-935]

Alert channels were passed as string names on the heartbeat CLI page,
API check headers were written as an object instead of an array of
key/value pairs, the environments config typed `locations` as
`string[]`, the environment-variables sample OR-ed a string literal
with a fallback (always truthy), and the heartbeat construct page's
advanced example referenced channels it never defined. Also rename the
deprecated `HeartbeatCheck` alias to `HeartbeatMonitor` on the heartbeat
CLI page so it matches the construct reference.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 cli/environment-variables.mdx                 |  7 +++---
 concepts/environments.mdx                     |  4 ++--
 constructs/heartbeat-monitor.mdx              | 11 ++++++++-
 .../api-checks/api-structure.mdx              |  6 ++---
 .../heartbeat-monitors/cli-configuration.mdx  | 24 ++++++++++++-------
 platform/secrets.mdx                          | 14 +++++------
 6 files changed, 42 insertions(+), 24 deletions(-)

diff --git a/cli/environment-variables.mdx b/cli/environment-variables.mdx
index 907e7a35..7640cb31 100644
--- a/cli/environment-variables.mdx
+++ b/cli/environment-variables.mdx
@@ -96,7 +96,7 @@ new ApiCheck('books-api-check-1', {
     entrypoint: path.join(__dirname, './utils/setup.ts'),
   },
   request: {
-    url: '{{ENVIRONMENT_URL}}' || 'https://danube-web.shop/api/books',
+    url: '{{ENVIRONMENT_URL}}',
     method: 'GET',
     followRedirects: true,
     skipSSL: false,
@@ -114,8 +114,9 @@ npx checkly test -e ENVIRONMENT_URL="https://staging.checklyhq.com"
 
 - Notice that we pass in the variable using the `-e` flag. This means it will be passed to the cloud environment and made
 available during runtime.
-- After deploying this check, the `ENVIRONMENT_URL` needs to be set at the Account, Group or Check level. If not set, the Check
-will use the fallback URL.
+- After deploying this check, the `ENVIRONMENT_URL` needs to be set at the Account, Group or Check level. Handlebars variables have no
+fallback, so the check will not work until the variable is set. Only script code, like the Playwright example above, can
+provide a fallback value.
 - Prepending the variable like `ENVIRONMENT_URL="https://staging.checklyhq.com" npx checkly test` has no effect as local
 environment variables are not replaced in code dependencies.
 
diff --git a/concepts/environments.mdx b/concepts/environments.mdx
index 78cac22e..10cb6dcd 100644
--- a/concepts/environments.mdx
+++ b/concepts/environments.mdx
@@ -54,7 +54,7 @@ The following example deploys one shared API check to development, staging, and
     Read the target environment from your CI pipeline and map it to a unique project `logicalId`.
 
     ```typescript checkly.config.ts
-    import { defineConfig } from "checkly"
+    import { defineConfig, type Region } from "checkly"
     import { Frequency } from "checkly/constructs"
 
     type Environment = "development" | "staging" | "production"
@@ -63,7 +63,7 @@ The following example deploys one shared API check to development, staging, and
       projectName: string
       logicalId: string
       frequency: Frequency
-      locations: string[]
+      locations: (keyof Region)[]
     }> = {
       development: {
         projectName: "My app - Development",
diff --git a/constructs/heartbeat-monitor.mdx b/constructs/heartbeat-monitor.mdx
index e450f14d..4dd6d481 100644
--- a/constructs/heartbeat-monitor.mdx
+++ b/constructs/heartbeat-monitor.mdx
@@ -38,7 +38,16 @@ new HeartbeatMonitor("daily-backup-heartbeat", {
 ```
 
 ```ts Advanced Example
-import { HeartbeatMonitor } from "checkly/constructs"
+import { HeartbeatMonitor, EmailAlertChannel, SlackAlertChannel } from "checkly/constructs"
+
+const emailChannel = new EmailAlertChannel("team-email", {
+  address: "team@example.com",
+})
+
+const slackChannel = new SlackAlertChannel("team-slack", {
+  url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
+  channel: "#ops",
+})
 
 new HeartbeatMonitor("newsletter-heartbeat", {
   name: "Weekly Newsletter Job",
diff --git a/detect/synthetic-monitoring/api-checks/api-structure.mdx b/detect/synthetic-monitoring/api-checks/api-structure.mdx
index 4682a820..d00a69dc 100644
--- a/detect/synthetic-monitoring/api-checks/api-structure.mdx
+++ b/detect/synthetic-monitoring/api-checks/api-structure.mdx
@@ -20,9 +20,9 @@ new ApiCheck('user-api-health', {
   request: {
     method: 'GET',
     url: 'https://api.example.com/v1/users/health',
-    headers: {
-      'Authorization': 'Bearer {{API_TOKEN}}'
-    },
+    headers: [
+      { key: 'Authorization', value: 'Bearer {{API_TOKEN}}' }
+    ],
     assertions: [
       AssertionBuilder.statusCode().equals(200),
       AssertionBuilder.responseTime().lessThan(2000),
diff --git a/detect/uptime-monitoring/heartbeat-monitors/cli-configuration.mdx b/detect/uptime-monitoring/heartbeat-monitors/cli-configuration.mdx
index c6cf5cbf..baa18460 100644
--- a/detect/uptime-monitoring/heartbeat-monitors/cli-configuration.mdx
+++ b/detect/uptime-monitoring/heartbeat-monitors/cli-configuration.mdx
@@ -19,9 +19,9 @@ Define heartbeat monitors as code alongside your other monitoring using the Chec
 ### TypeScript Example
 
 ```typescript
-import { HeartbeatCheck } from 'checkly/constructs'
+import { HeartbeatMonitor } from 'checkly/constructs'
 
-new HeartbeatCheck('weekly-newsletter', {
+new HeartbeatMonitor('weekly-newsletter', {
   name: 'Weekly Newsletter Campaign',
   period: 7,
   periodUnit: 'days',
@@ -30,7 +30,7 @@ new HeartbeatCheck('weekly-newsletter', {
   tags: ['newsletter', 'marketing', 'weekly']
 })
 
-new HeartbeatCheck('database-backup', {
+new HeartbeatMonitor('database-backup', {
   name: 'Nightly Database Backup',
   period: 1,
   periodUnit: 'days', 
@@ -43,9 +43,9 @@ new HeartbeatCheck('database-backup', {
 ### JavaScript Example
 
 ```javascript
-const { HeartbeatCheck } = require('checkly/constructs')
+const { HeartbeatMonitor } = require('checkly/constructs')
 
-new HeartbeatCheck('data-sync', {
+new HeartbeatMonitor('data-sync', {
   name: 'Hourly Data Sync',
   period: 1,
   periodUnit: 'hours',
@@ -58,16 +58,24 @@ new HeartbeatCheck('data-sync', {
 ### Advanced CLI Configuration
 
 ```typescript
-import { HeartbeatCheck } from 'checkly/constructs'
+import { HeartbeatMonitor, EmailAlertChannel, SlackAlertChannel } from 'checkly/constructs'
 
-new HeartbeatCheck('production-backup', {
+const email = new EmailAlertChannel('email', {
+  address: 'ops@example.com'
+})
+const slackCritical = new SlackAlertChannel('slack-critical', {
+  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
+  channel: '#critical'
+})
+
+new HeartbeatMonitor('production-backup', {
   name: 'Production Database Backup',
   period: 24,
   periodUnit: 'hours',
   grace: 60,
   graceUnit: 'minutes',
   tags: ['production', 'backup', 'critical'],
-  alertChannels: ['email', 'slack-critical'],
+  alertChannels: [email, slackCritical],
   activated: true,
   muted: false
 })
diff --git a/platform/secrets.mdx b/platform/secrets.mdx
index 743428cf..7fcd199e 100644
--- a/platform/secrets.mdx
+++ b/platform/secrets.mdx
@@ -37,11 +37,11 @@ new ApiCheck('authenticated-api-check', {
   request: {
     method: 'GET',
     url: 'https://api.example.com/user/profile',
-    headers: {
+    headers: [
       // Secret API key - never visible in logs or UI
-      'Authorization': 'Bearer {{API_SECRET_KEY}}',
-      'Content-Type': 'application/json'
-    },
+      { key: 'Authorization', value: 'Bearer {{API_SECRET_KEY}}' },
+      { key: 'Content-Type', value: 'application/json' }
+    ],
     assertions: [
       AssertionBuilder.statusCode().equals(200),
       AssertionBuilder.jsonBody('user.email').isNotNull()
@@ -79,9 +79,9 @@ new ApiCheck('database-health-check', {
   request: {
     method: 'POST',
     url: 'https://api.example.com/health/database',
-    headers: {
-      'Authorization': 'Bearer {{DB_MONITORING_TOKEN}}'
-    },
+    headers: [
+      { key: 'Authorization', value: 'Bearer {{DB_MONITORING_TOKEN}}' }
+    ],
     body: JSON.stringify({
       // Secret database connection string
       connectionString: '{{DATABASE_CONNECTION_STRING}}'

From f83e0c043976b15115d7fd15a188855ad9d92a45 Mon Sep 17 00:00:00 2001
From: Simo Kinnunen <simo@checklyhq.com>
Date: Fri, 4 Sep 2026 21:28:15 +0900
Subject: [PATCH 4/8] docs: use the Slack App alert channel in the rewritten
 CLI samples [RED-935]

The Slack App integration is the preferred way to send alerts to Slack;
the webhook-based SlackAlertChannel is the legacy option. Switch the
samples introduced on the uptime and heartbeat CLI pages to
SlackAppAlertChannel.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 constructs/heartbeat-monitor.mdx              |  7 ++--
 .../uptime-monitoring/cli-configuration.mdx   | 42 ++++++++-----------
 .../heartbeat-monitors/cli-configuration.mdx  |  7 ++--
 3 files changed, 24 insertions(+), 32 deletions(-)

diff --git a/constructs/heartbeat-monitor.mdx b/constructs/heartbeat-monitor.mdx
index 4dd6d481..8d380d0a 100644
--- a/constructs/heartbeat-monitor.mdx
+++ b/constructs/heartbeat-monitor.mdx
@@ -38,15 +38,14 @@ new HeartbeatMonitor("daily-backup-heartbeat", {
 ```
 
 ```ts Advanced Example
-import { HeartbeatMonitor, EmailAlertChannel, SlackAlertChannel } from "checkly/constructs"
+import { HeartbeatMonitor, EmailAlertChannel, SlackAppAlertChannel } from "checkly/constructs"
 
 const emailChannel = new EmailAlertChannel("team-email", {
   address: "team@example.com",
 })
 
-const slackChannel = new SlackAlertChannel("team-slack", {
-  url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
-  channel: "#ops",
+const slackChannel = new SlackAppAlertChannel("team-slack", {
+  slackChannels: ["#ops"]
 })
 
 new HeartbeatMonitor("newsletter-heartbeat", {
diff --git a/detect/uptime-monitoring/cli-configuration.mdx b/detect/uptime-monitoring/cli-configuration.mdx
index ec8115ae..08de121e 100644
--- a/detect/uptime-monitoring/cli-configuration.mdx
+++ b/detect/uptime-monitoring/cli-configuration.mdx
@@ -82,14 +82,13 @@ The samples on this page define their alert channels inline to stay self-contain
 <CodeGroup dropdown>
 
 ```ts api-monitor.check.ts
-import { UrlMonitor, UrlAssertionBuilder, EmailAlertChannel, SlackAlertChannel } from 'checkly/constructs'
+import { UrlMonitor, UrlAssertionBuilder, EmailAlertChannel, SlackAppAlertChannel } from 'checkly/constructs'
 
 const emailAlerts = new EmailAlertChannel('email-alerts', {
   address: 'ops@myapp.com'
 })
-const slackAlerts = new SlackAlertChannel('slack-alerts', {
-  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
-  channel: '#alerts'
+const slackAlerts = new SlackAppAlertChannel('slack-alerts', {
+  slackChannels: ['#alerts']
 })
 
 new UrlMonitor('api-health-check', {
@@ -111,14 +110,13 @@ new UrlMonitor('api-health-check', {
 ```
 
 ```js api-monitor.check.js
-const { UrlMonitor, UrlAssertionBuilder, EmailAlertChannel, SlackAlertChannel } = require('checkly/constructs')
+const { UrlMonitor, UrlAssertionBuilder, EmailAlertChannel, SlackAppAlertChannel } = require('checkly/constructs')
 
 const emailAlerts = new EmailAlertChannel('email-alerts', {
   address: 'ops@myapp.com'
 })
-const slackAlerts = new SlackAlertChannel('slack-alerts', {
-  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
-  channel: '#alerts'
+const slackAlerts = new SlackAppAlertChannel('slack-alerts', {
+  slackChannels: ['#alerts']
 })
 
 new UrlMonitor('api-health-check', {
@@ -272,15 +270,14 @@ new HeartbeatMonitor('daily-backup-heartbeat', {
 <CodeGroup dropdown>
 
 ```ts sync-job-heartbeat.check.ts
-import { HeartbeatMonitor, PagerdutyAlertChannel, SlackAlertChannel } from 'checkly/constructs'
+import { HeartbeatMonitor, PagerdutyAlertChannel, SlackAppAlertChannel } from 'checkly/constructs'
 
 const pagerdutyCritical = new PagerdutyAlertChannel('pagerduty-critical', {
   serviceName: 'Data platform',
   serviceKey: 'your-pagerduty-integration-key'
 })
-const slackOps = new SlackAlertChannel('slack-ops', {
-  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
-  channel: '#ops'
+const slackOps = new SlackAppAlertChannel('slack-ops', {
+  slackChannels: ['#ops']
 })
 
 new HeartbeatMonitor('hourly-sync-heartbeat', {
@@ -296,15 +293,14 @@ new HeartbeatMonitor('hourly-sync-heartbeat', {
 ```
 
 ```js sync-job-heartbeat.check.js
-const { HeartbeatMonitor, PagerdutyAlertChannel, SlackAlertChannel } = require('checkly/constructs')
+const { HeartbeatMonitor, PagerdutyAlertChannel, SlackAppAlertChannel } = require('checkly/constructs')
 
 const pagerdutyCritical = new PagerdutyAlertChannel('pagerduty-critical', {
   serviceName: 'Data platform',
   serviceKey: 'your-pagerduty-integration-key'
 })
-const slackOps = new SlackAlertChannel('slack-ops', {
-  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
-  channel: '#ops'
+const slackOps = new SlackAppAlertChannel('slack-ops', {
+  slackChannels: ['#ops']
 })
 
 new HeartbeatMonitor('hourly-sync-heartbeat', {
@@ -330,14 +326,13 @@ Organize related monitors using groups:
 <CodeGroup dropdown>
 
 ```ts api-monitoring-group.check.ts
-import { CheckGroupV2, UrlMonitor, EmailAlertChannel, SlackAlertChannel } from 'checkly/constructs'
+import { CheckGroupV2, UrlMonitor, EmailAlertChannel, SlackAppAlertChannel } from 'checkly/constructs'
 
 const emailAlerts = new EmailAlertChannel('email-alerts', {
   address: 'ops@myapp.com'
 })
-const slackApiAlerts = new SlackAlertChannel('slack-api-alerts', {
-  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
-  channel: '#api-alerts'
+const slackApiAlerts = new SlackAppAlertChannel('slack-api-alerts', {
+  slackChannels: ['#api-alerts']
 })
 
 const apiGroup = new CheckGroupV2('api-monitoring', {
@@ -368,14 +363,13 @@ new UrlMonitor('orders-api', {
 ```
 
 ```js api-monitoring-group.check.js
-const { CheckGroupV2, UrlMonitor, EmailAlertChannel, SlackAlertChannel } = require('checkly/constructs')
+const { CheckGroupV2, UrlMonitor, EmailAlertChannel, SlackAppAlertChannel } = require('checkly/constructs')
 
 const emailAlerts = new EmailAlertChannel('email-alerts', {
   address: 'ops@myapp.com'
 })
-const slackApiAlerts = new SlackAlertChannel('slack-api-alerts', {
-  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
-  channel: '#api-alerts'
+const slackApiAlerts = new SlackAppAlertChannel('slack-api-alerts', {
+  slackChannels: ['#api-alerts']
 })
 
 const apiGroup = new CheckGroupV2('api-monitoring', {
diff --git a/detect/uptime-monitoring/heartbeat-monitors/cli-configuration.mdx b/detect/uptime-monitoring/heartbeat-monitors/cli-configuration.mdx
index baa18460..94ca163f 100644
--- a/detect/uptime-monitoring/heartbeat-monitors/cli-configuration.mdx
+++ b/detect/uptime-monitoring/heartbeat-monitors/cli-configuration.mdx
@@ -58,14 +58,13 @@ new HeartbeatMonitor('data-sync', {
 ### Advanced CLI Configuration
 
 ```typescript
-import { HeartbeatMonitor, EmailAlertChannel, SlackAlertChannel } from 'checkly/constructs'
+import { HeartbeatMonitor, EmailAlertChannel, SlackAppAlertChannel } from 'checkly/constructs'
 
 const email = new EmailAlertChannel('email', {
   address: 'ops@example.com'
 })
-const slackCritical = new SlackAlertChannel('slack-critical', {
-  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
-  channel: '#critical'
+const slackCritical = new SlackAppAlertChannel('slack-critical', {
+  slackChannels: ['#critical']
 })
 
 new HeartbeatMonitor('production-backup', {

From 16de86c796b50bda1da29877fa71d236bbe74c2b Mon Sep 17 00:00:00 2001
From: Simo Kinnunen <simo@checklyhq.com>
Date: Fri, 4 Sep 2026 21:43:35 +0900
Subject: [PATCH 5/8] docs: use Frequency constants instead of numeric minutes
 in CLI samples [RED-935]

`frequency: 5` reads as an ambiguous number; `Frequency.EVERY_5M` makes
the unit explicit. Replace the numeric form in every hand-written CLI
construct and checkly.config.ts sample and add the import to each
block. Blocks that show what `checkly init` or `checkly pw-test
--create-check` generate keep the number, because the CLI writes a
number there. Pulumi, Terraform, and REST payload samples are unchanged
since those APIs take numbers. Also point the add-to-group highlights at
the `group` lines the prose describes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 cli/checkly-pw-test.mdx                       |  3 +-
 .../playwright-checks/add-to-group.mdx        | 14 +++--
 detect/testing/creating-your-first-test.mdx   |  5 +-
 .../uptime-monitoring/cli-configuration.mdx   | 56 +++++++++----------
 guides/claude-code-monitoring.mdx             |  6 +-
 guides/create-multiple-monitors.mdx           | 14 ++---
 ...toring-ecommerce-apps-using-playwright.mdx | 13 +++--
 ...artup-guide-detect-communicate-resolve.mdx | 12 ++--
 platform/manage-secrets-at-scale.mdx          |  4 +-
 9 files changed, 66 insertions(+), 61 deletions(-)

diff --git a/cli/checkly-pw-test.mdx b/cli/checkly-pw-test.mdx
index 68546317..ff13da33 100644
--- a/cli/checkly-pw-test.mdx
+++ b/cli/checkly-pw-test.mdx
@@ -102,7 +102,8 @@ Running this command:
 
 Adds a new Playwright Check Suite to your `checkly.config.ts`:
 
-```typescript checkly.config.ts highlight={8-15}
+```typescript checkly.config.ts highlight={9-16}
+import { defineConfig } from 'checkly'
 const config = defineConfig({
   projectName: "Playwright Project",
   logicalId: "playwright-project",
diff --git a/detect/synthetic-monitoring/playwright-checks/add-to-group.mdx b/detect/synthetic-monitoring/playwright-checks/add-to-group.mdx
index 8f167b28..6798618b 100644
--- a/detect/synthetic-monitoring/playwright-checks/add-to-group.mdx
+++ b/detect/synthetic-monitoring/playwright-checks/add-to-group.mdx
@@ -40,8 +40,9 @@ Learn more about [using groups](/constructs/check-group-v2).
 
 Import the group and reference it in your Playwright Check Suite configuration:
 
-```typescript checkly.config.ts highlight={2,14}
+```typescript checkly.config.ts highlight={3,17}
 import { defineConfig } from 'checkly'
+import { Frequency } from 'checkly/constructs'
 import { myGroup } from './website-group.check'
 
 export default defineConfig({
@@ -54,7 +55,7 @@ export default defineConfig({
         name: 'Critical Tests',
         logicalId: 'critical-tests',
         pwTags:'critical',
-        frequency: 10,
+        frequency: Frequency.EVERY_10M,
         locations: ['us-east-1',],
         group: myGroup,
       },
@@ -76,8 +77,9 @@ Your Playwright Check Suite now appears in the group in your [Checkly Home Dashb
 
 Add multiple Playwright Check Suites to the same group while keeping individual test selection and frequency settings. Reference the group in each suite:
 
-```typescript checkly.config.ts highlight={2,13,20,27}
+```typescript checkly.config.ts highlight={3,16,23,30}
 import { defineConfig } from 'checkly'
+import { Frequency } from 'checkly/constructs'
 import { myGroup } from './website-group.check'
 
 export default defineConfig({
@@ -90,21 +92,21 @@ export default defineConfig({
         name: 'Critical User Flows',
         logicalId: 'critical-flows',
         pwTags: 'critical',
-        frequency: 5,
+        frequency: Frequency.EVERY_5M,
         group: myGroup,
       },
       {
         name: 'Authentication Tests',
         logicalId: 'auth-tests',
         pwTags: 'auth',
-        frequency: 10,
+        frequency: Frequency.EVERY_10M,
         group: myGroup,
       },
       {
         name: 'Checkout Flow',
         logicalId: 'checkout-flow',
         pwTags: 'checkout',
-        frequency: 5,
+        frequency: Frequency.EVERY_5M,
         group: myGroup,
       },
     ],
diff --git a/detect/testing/creating-your-first-test.mdx b/detect/testing/creating-your-first-test.mdx
index 4c2f07ae..22d965c7 100644
--- a/detect/testing/creating-your-first-test.mdx
+++ b/detect/testing/creating-your-first-test.mdx
@@ -56,6 +56,7 @@ Open `checkly.config.ts` to configure your monitoring setup:
 
 ```ts Checkly.config.ts
 import { defineConfig } from '@checkly/cli'
+import { Frequency } from '@checkly/cli/constructs'
 
 export default defineConfig({
   projectName: 'My First Checkly Project',
@@ -66,13 +67,13 @@ export default defineConfig({
     activated: true,
     muted: false,
     runtimeId: '2025.04',
-    frequency: 5, // Run every 5 minutes
+    frequency: Frequency.EVERY_5M,
     locations: ['us-east-1', 'eu-west-1'], // Global locations
     tags: ['production', 'critical'],
     
     // Browser check specific settings
     browserChecks: {
-      frequency: 10, // Browser checks every 10 minutes
+      frequency: Frequency.EVERY_10M,
       testMatch: '**/__checks__/*.spec.ts',
     },
   },
diff --git a/detect/uptime-monitoring/cli-configuration.mdx b/detect/uptime-monitoring/cli-configuration.mdx
index 08de121e..bbc0dbab 100644
--- a/detect/uptime-monitoring/cli-configuration.mdx
+++ b/detect/uptime-monitoring/cli-configuration.mdx
@@ -34,13 +34,13 @@ This creates the basic project structure with configuration files and example mo
 <CodeGroup dropdown>
 
 ```ts url-monitor.check.ts
-import { UrlMonitor, UrlAssertionBuilder } from 'checkly/constructs'
+import { Frequency, UrlMonitor, UrlAssertionBuilder } from 'checkly/constructs'
 
 new UrlMonitor('homepage-check', {
   name: 'Homepage Availability',
   activated: true,
   locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],
-  frequency: 5, // minutes
+  frequency: Frequency.EVERY_5M,
   maxResponseTime: 2000, // ms
   request: {
     url: 'https://www.myapp.com',
@@ -53,13 +53,13 @@ new UrlMonitor('homepage-check', {
 ```
 
 ```js url-monitor.check.js
-const { UrlMonitor, UrlAssertionBuilder } = require('checkly/constructs')
+const { Frequency, UrlMonitor, UrlAssertionBuilder } = require('checkly/constructs')
 
 new UrlMonitor('homepage-check', {
   name: 'Homepage Availability',
   activated: true,
   locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],
-  frequency: 5, // minutes
+  frequency: Frequency.EVERY_5M,
   maxResponseTime: 2000, // ms
   request: {
     url: 'https://www.myapp.com',
@@ -82,7 +82,7 @@ The samples on this page define their alert channels inline to stay self-contain
 <CodeGroup dropdown>
 
 ```ts api-monitor.check.ts
-import { UrlMonitor, UrlAssertionBuilder, EmailAlertChannel, SlackAppAlertChannel } from 'checkly/constructs'
+import { Frequency, UrlMonitor, UrlAssertionBuilder, EmailAlertChannel, SlackAppAlertChannel } from 'checkly/constructs'
 
 const emailAlerts = new EmailAlertChannel('email-alerts', {
   address: 'ops@myapp.com'
@@ -95,7 +95,7 @@ new UrlMonitor('api-health-check', {
   name: 'API Health Check',
   activated: true,
   locations: ['us-east-1', 'eu-west-1'],
-  frequency: 2, // minutes
+  frequency: Frequency.EVERY_2M,
   degradedResponseTime: 500, // ms
   maxResponseTime: 1000, // ms
   request: {
@@ -110,7 +110,7 @@ new UrlMonitor('api-health-check', {
 ```
 
 ```js api-monitor.check.js
-const { UrlMonitor, UrlAssertionBuilder, EmailAlertChannel, SlackAppAlertChannel } = require('checkly/constructs')
+const { Frequency, UrlMonitor, UrlAssertionBuilder, EmailAlertChannel, SlackAppAlertChannel } = require('checkly/constructs')
 
 const emailAlerts = new EmailAlertChannel('email-alerts', {
   address: 'ops@myapp.com'
@@ -123,7 +123,7 @@ new UrlMonitor('api-health-check', {
   name: 'API Health Check',
   activated: true,
   locations: ['us-east-1', 'eu-west-1'],
-  frequency: 2, // minutes
+  frequency: Frequency.EVERY_2M,
   degradedResponseTime: 500, // ms
   maxResponseTime: 1000, // ms
   request: {
@@ -146,13 +146,13 @@ new UrlMonitor('api-health-check', {
 <CodeGroup dropdown>
 
 ```ts database-monitor.check.ts
-import { TcpMonitor } from 'checkly/constructs'
+import { Frequency, TcpMonitor } from 'checkly/constructs'
 
 new TcpMonitor('database-tcp-check', {
   name: 'Production Database Connection',
   activated: true,
   locations: ['us-east-1', 'eu-west-1'],
-  frequency: 5, // minutes
+  frequency: Frequency.EVERY_5M,
   degradedResponseTime: 3000, // ms
   request: {
     hostname: 'db.myapp.com',
@@ -163,13 +163,13 @@ new TcpMonitor('database-tcp-check', {
 ```
 
 ```js database-monitor.check.js
-const { TcpMonitor } = require('checkly/constructs')
+const { Frequency, TcpMonitor } = require('checkly/constructs')
 
 new TcpMonitor('database-tcp-check', {
   name: 'Production Database Connection',
   activated: true,
   locations: ['us-east-1', 'eu-west-1'],
-  frequency: 5, // minutes
+  frequency: Frequency.EVERY_5M,
   degradedResponseTime: 3000, // ms
   request: {
     hostname: 'db.myapp.com',
@@ -186,13 +186,13 @@ new TcpMonitor('database-tcp-check', {
 <CodeGroup dropdown>
 
 ```ts mail-server-monitor.check.ts
-import { TcpMonitor, TcpAssertionBuilder } from 'checkly/constructs'
+import { Frequency, TcpMonitor, TcpAssertionBuilder } from 'checkly/constructs'
 
 new TcpMonitor('mail-server-check', {
   name: 'SMTP Server Monitoring',
   activated: true,
   locations: ['us-east-1', 'eu-west-1'],
-  frequency: 10, // minutes
+  frequency: Frequency.EVERY_10M,
   degradedResponseTime: 3000, // ms
   request: {
     hostname: 'mail.myapp.com',
@@ -207,13 +207,13 @@ new TcpMonitor('mail-server-check', {
 ```
 
 ```js mail-server-monitor.check.js
-const { TcpMonitor, TcpAssertionBuilder } = require('checkly/constructs')
+const { Frequency, TcpMonitor, TcpAssertionBuilder } = require('checkly/constructs')
 
 new TcpMonitor('mail-server-check', {
   name: 'SMTP Server Monitoring',
   activated: true,
   locations: ['us-east-1', 'eu-west-1'],
-  frequency: 10, // minutes
+  frequency: Frequency.EVERY_10M,
   degradedResponseTime: 3000, // ms
   request: {
     hostname: 'mail.myapp.com',
@@ -326,7 +326,7 @@ Organize related monitors using groups:
 <CodeGroup dropdown>
 
 ```ts api-monitoring-group.check.ts
-import { CheckGroupV2, UrlMonitor, EmailAlertChannel, SlackAppAlertChannel } from 'checkly/constructs'
+import { Frequency, CheckGroupV2, UrlMonitor, EmailAlertChannel, SlackAppAlertChannel } from 'checkly/constructs'
 
 const emailAlerts = new EmailAlertChannel('email-alerts', {
   address: 'ops@myapp.com'
@@ -339,7 +339,7 @@ const apiGroup = new CheckGroupV2('api-monitoring', {
   name: 'API Monitoring',
   activated: true,
   locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],
-  frequency: 5,
+  frequency: Frequency.EVERY_5M,
   alertChannels: [emailAlerts, slackApiAlerts],
   tags: ['api', 'production']
 })
@@ -363,7 +363,7 @@ new UrlMonitor('orders-api', {
 ```
 
 ```js api-monitoring-group.check.js
-const { CheckGroupV2, UrlMonitor, EmailAlertChannel, SlackAppAlertChannel } = require('checkly/constructs')
+const { Frequency, CheckGroupV2, UrlMonitor, EmailAlertChannel, SlackAppAlertChannel } = require('checkly/constructs')
 
 const emailAlerts = new EmailAlertChannel('email-alerts', {
   address: 'ops@myapp.com'
@@ -376,7 +376,7 @@ const apiGroup = new CheckGroupV2('api-monitoring', {
   name: 'API Monitoring',
   activated: true,
   locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],
-  frequency: 5,
+  frequency: Frequency.EVERY_5M,
   alertChannels: [emailAlerts, slackApiAlerts],
   tags: ['api', 'production']
 })
@@ -408,7 +408,7 @@ Use environment variables to vary the configuration per environment:
 <CodeGroup dropdown>
 
 ```ts environment-config.check.ts
-import { UrlMonitor, UrlAssertionBuilder } from 'checkly/constructs'
+import { Frequency, UrlMonitor, UrlAssertionBuilder } from 'checkly/constructs'
 
 // Environment-specific configuration
 const baseUrl = process.env.BASE_URL || 'https://api.myapp.com'
@@ -420,7 +420,7 @@ new UrlMonitor(`${environment}-api-check`, {
   locations: environment === 'production'
     ? ['us-east-1', 'eu-west-1', 'ap-southeast-1']
     : ['us-east-1'],
-  frequency: environment === 'production' ? 2 : 10,
+  frequency: environment === 'production' ? Frequency.EVERY_2M : Frequency.EVERY_10M,
   maxResponseTime: environment === 'production' ? 2000 : 5000, // ms
   request: {
     url: `${baseUrl}/health`,
@@ -433,7 +433,7 @@ new UrlMonitor(`${environment}-api-check`, {
 ```
 
 ```js environment-config.check.js
-const { UrlMonitor, UrlAssertionBuilder } = require('checkly/constructs')
+const { Frequency, UrlMonitor, UrlAssertionBuilder } = require('checkly/constructs')
 
 // Environment-specific configuration
 const baseUrl = process.env.BASE_URL || 'https://api.myapp.com'
@@ -445,7 +445,7 @@ new UrlMonitor(`${environment}-api-check`, {
   locations: environment === 'production'
     ? ['us-east-1', 'eu-west-1', 'ap-southeast-1']
     : ['us-east-1'],
-  frequency: environment === 'production' ? 2 : 10,
+  frequency: environment === 'production' ? Frequency.EVERY_2M : Frequency.EVERY_10M,
   maxResponseTime: environment === 'production' ? 2000 : 5000, // ms
   request: {
     url: `${baseUrl}/health`,
@@ -530,7 +530,7 @@ Generate monitors programmatically:
 <CodeGroup dropdown>
 
 ```ts dynamic-monitors.check.ts
-import { UrlMonitor, UrlAssertionBuilder } from 'checkly/constructs'
+import { Frequency, UrlMonitor, UrlAssertionBuilder } from 'checkly/constructs'
 
 // Monitor multiple API endpoints
 const endpoints = [
@@ -545,7 +545,7 @@ endpoints.forEach((endpoint, index) => {
     name: endpoint.name,
     activated: true,
     locations: ['us-east-1', 'eu-west-1'],
-    frequency: endpoint.path === '/payments' ? 1 : 5, // More frequent for critical endpoints
+    frequency: endpoint.path === '/payments' ? Frequency.EVERY_1M : Frequency.EVERY_5M, // More frequent for critical endpoints
     maxResponseTime: endpoint.path === '/payments' ? 500 : 1000, // Stricter limit for critical endpoints
     request: {
       url: `https://api.myapp.com${endpoint.path}`,
@@ -559,7 +559,7 @@ endpoints.forEach((endpoint, index) => {
 ```
 
 ```js dynamic-monitors.check.js
-const { UrlMonitor, UrlAssertionBuilder } = require('checkly/constructs')
+const { Frequency, UrlMonitor, UrlAssertionBuilder } = require('checkly/constructs')
 
 // Monitor multiple API endpoints
 const endpoints = [
@@ -574,7 +574,7 @@ endpoints.forEach((endpoint, index) => {
     name: endpoint.name,
     activated: true,
     locations: ['us-east-1', 'eu-west-1'],
-    frequency: endpoint.path === '/payments' ? 1 : 5, // More frequent for critical endpoints
+    frequency: endpoint.path === '/payments' ? Frequency.EVERY_1M : Frequency.EVERY_5M, // More frequent for critical endpoints
     maxResponseTime: endpoint.path === '/payments' ? 500 : 1000, // Stricter limit for critical endpoints
     request: {
       url: `https://api.myapp.com${endpoint.path}`,
diff --git a/guides/claude-code-monitoring.mdx b/guides/claude-code-monitoring.mdx
index 74015f55..4fe3981b 100644
--- a/guides/claude-code-monitoring.mdx
+++ b/guides/claude-code-monitoring.mdx
@@ -162,7 +162,7 @@ Add comments to the check.ts file defining how each line configures the checkly
 The result is a nicely commented version of and a good tour of this construct:
 ```ts {title="book-detail-visibility.check.ts"}
 // Import Checkly constructs for browser checks, alert escalation, and retry strategies
-import { AlertEscalationBuilder, BrowserCheck, RetryStrategyBuilder } from 'checkly/constructs'
+import { Frequency, AlertEscalationBuilder, BrowserCheck, RetryStrategyBuilder } from 'checkly/constructs'
 
 // Create a new browser check with unique logical ID
 new BrowserCheck('book-detail-visibility-check-v1', {
@@ -184,8 +184,8 @@ new BrowserCheck('book-detail-visibility-check-v1', {
     'us-east-1', // US East (N. Virginia)
     'eu-west-1', // EU West (Ireland)
   ],
-  // How often the check runs in minutes
-  frequency: 30,
+  // How often the check runs
+  frequency: Frequency.EVERY_30M,
   // Alert escalation policy defining when and how alerts are sent
   alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
     // Number of failed runs before sending alert (0 = immediate)
diff --git a/guides/create-multiple-monitors.mdx b/guides/create-multiple-monitors.mdx
index 5d6e47a0..d9e1cffb 100644
--- a/guides/create-multiple-monitors.mdx
+++ b/guides/create-multiple-monitors.mdx
@@ -20,12 +20,12 @@ Checkly's Monitoring as Code workflow starts with creating a [project](/construc
 If you haven't worked with Checkly at all, or have only created new monitors from our web UI, [install the Checkly CLI and create a new project for our checks with our getting started guide here](/cli/overview). A basic URL monitor with minimal configuration looks like this:
 
 ```ts {title="first-url-monitor.check.ts"}
-import { UrlAssertionBuilder, UrlMonitor } from 'checkly/constructs' 
+import { Frequency, UrlAssertionBuilder, UrlMonitor } from 'checkly/constructs' 
 
 new UrlMonitor('url-monitor-001', { // the monitor's unique logical ID
   name: 'Example URL Monitor', // display name to show in the Checkly UI
   activated: true, 
-  frequency: 1, // frequency in minutes 
+  frequency: Frequency.EVERY_1M,
   maxResponseTime: 10000, // milliseconds
   request: {
     url: 'https://www.checklyhq.com/learn/', // target URL
@@ -89,7 +89,7 @@ sitemapUrls.forEach((url, index) => {
   new UrlMonitor(logicalId, {
     name: `URL Monitor - ${url}`,
     activated: true,
-    frequency: 5, // Check every 5 minutes
+    frequency: Frequency.EVERY_5M,
     maxResponseTime: 10000,
     degradedResponseTime: 5000,
     request: {
@@ -175,7 +175,7 @@ Let’s continue to increase the sophistication of our group of monitors. Right
 And this version of the URL monitor fetches the CSV and parses the three values for each check from the row before creating a monitor.
 
 ```ts {title="csv-import-url-monitors.check.ts"}
-import { UrlAssertionBuilder, UrlMonitor } from 'checkly/constructs'
+import { Frequency, UrlAssertionBuilder, UrlMonitor } from 'checkly/constructs'
 const csvUrl = 'https://raw.githubusercontent.com/serverless-mom/claudeExperiments/refs/heads/main/urlsWithIds.csv'
 
 interface CsvRow {
@@ -217,7 +217,7 @@ urlsToMonitor.forEach((row) => {
   new UrlMonitor(row.logicalId, {
     name: row.name,
     activated: true,
-    frequency: 5,
+    frequency: Frequency.EVERY_5M,
     maxResponseTime: 10000,
     request: {
       url: row.url,
@@ -242,12 +242,12 @@ As you handle monitors for multiple sites and environments, inevitably you'll wa
 We can create a group with constructs:
 
 ```ts {title="prod-monitoring-group.ts"}
-import { CheckGroupV2 } from 'checkly/constructs'
+import { Frequency, CheckGroupV2 } from 'checkly/constructs'
 
 export const prodMonitorGroup = new CheckGroupV2('prod-monitor-group', {
   name: 'Prod Monitor Group',
   activated: true,
-  frequency: 5,
+  frequency: Frequency.EVERY_5M,
   locations: ['us-east-1', 'eu-west-1'],
   tags: ['url-monitoring', 'production'],
   environmentVariables: [],
diff --git a/guides/monitoring-ecommerce-apps-using-playwright.mdx b/guides/monitoring-ecommerce-apps-using-playwright.mdx
index 4d3d10b6..f93b5354 100644
--- a/guides/monitoring-ecommerce-apps-using-playwright.mdx
+++ b/guides/monitoring-ecommerce-apps-using-playwright.mdx
@@ -197,6 +197,7 @@ Next up, we want to create our `checkly.config.ts` file and include the basic Ch
 <Tab title="checkly.config.ts">
 ```ts checkly.config.ts
 import { defineConfig } from '@checkly/cli'
+import { Frequency } from '@checkly/cli/constructs'
 
 export default defineConfig({
  projectName: 'Website Monitoring',
@@ -206,14 +207,14 @@ export default defineConfig({
    activated: true,
    muted: false,
    runtimeId: '2022.10',
-   frequency: 5,
+   frequency: Frequency.EVERY_5M,
    locations: ['us-east-1', 'eu-west-1'],
    tags: ['website', 'api'],
    alertChannels: [],
    checkMatch: '**/__checks__/*.check.ts',
    ignoreDirectoriesMatch: [],
    browserChecks: {
-     frequency: 10,
+     frequency: Frequency.EVERY_10M,
      testMatch: '**/__checks__/*.spec.ts',
    },
  },
@@ -285,12 +286,12 @@ Browser Checks are now there to keep us informed on the status of our key websit
 <Tab title="API check resource">
 ```ts api.check.ts
 // __check__/api.check.ts
-import { ApiCheck, AssertionBuilder } from '@checkly/cli/constructs'
+import { Frequency, ApiCheck, AssertionBuilder } from '@checkly/cli/constructs'
 
 const api = new ApiCheck('webstore-list-books', {
   name: 'List Books API',
   locations: ['eu-central-1','us-west-1'], // overrides the locations property
-  frequency: 1, // overrides the frequency property
+  frequency: Frequency.EVERY_1M, // overrides the frequency property
   degradedResponseTime: 5000,
   maxResponseTime: 10000,
   request: {
@@ -334,14 +335,14 @@ We are setting up things so that we are alerted when our Check starts failing, a
 
 ```ts api.check.ts
 // __check__/api.check.ts
-import { ApiCheck, AssertionBuilder } from '@checkly/cli/constructs'
+import { Frequency, ApiCheck, AssertionBuilder } from '@checkly/cli/constructs'
 import { emailChannel } from './alert-Channels'
 
 const api = new ApiCheck('webstore-list-books', {
   name: 'List Books API',
   alertChannels: [emailChannel],
   locations: ['eu-central-1','us-west-1'], // overrides the locations property
-  frequency: 1, // overrides the frequency property
+  frequency: Frequency.EVERY_1M, // overrides the frequency property
   degradedResponseTime: 5000,
   maxResponseTime: 10000,
   request: {
diff --git a/guides/startup-guide-detect-communicate-resolve.mdx b/guides/startup-guide-detect-communicate-resolve.mdx
index d9a218dd..cbba0f3b 100644
--- a/guides/startup-guide-detect-communicate-resolve.mdx
+++ b/guides/startup-guide-detect-communicate-resolve.mdx
@@ -88,12 +88,12 @@ With a project set up, we can start writing our first monitors. Monitors come in
 All monitors are created as `.check.ts` files implementing the [Checkly CLI construct](/constructs/overview). Here’s an example URL Monitor:
 
 ```ts
-import { UrlAssertionBuilder, UrlMonitor } from 'checkly/constructs' // Import required constructs from Checkly CLI
+import { Frequency, UrlAssertionBuilder, UrlMonitor } from 'checkly/constructs' // Import required constructs from Checkly CLI
 
 new UrlMonitor('url-monitor-example', { // Create new URL monitor with unique logical ID
   name: 'Example URL Monitor', // Human-readable name for the monitor
   activated: true, // Enable the monitor to run checks
-  frequency: 1, // Run check every 1 minute
+  frequency: Frequency.EVERY_1M,
   maxResponseTime: 10000, // Maximum response time in milliseconds before marking as failed
   degradedResponseTime: 5000, // Response time in milliseconds for degraded performance warning
   request: { // Configure the HTTP request settings (required)
@@ -259,7 +259,7 @@ A Chromium browser and a new "Playwright inspector" window should appear. As you
 Once you’re happy with the scripted test, copy the code into a `.spec.ts` file, and create a construct for your check as a `.check.ts` file, based  on the CLI [constructs; this time for browser checks](/constructs/overview#browsercheck). Here’s an example of a check for the demo site [Danube Web Shop](https://danube-web.shop/):
 
 ```ts {title="homepage-browse.check.ts"}
-import { AlertEscalationBuilder, BrowserCheck, RetryStrategyBuilder } from 'checkly/constructs'
+import { Frequency, AlertEscalationBuilder, BrowserCheck, RetryStrategyBuilder } from 'checkly/constructs'
 
 new BrowserCheck('browse-danube-homepage-v1', {
   name: 'Browse Danube Homepage',
@@ -274,7 +274,7 @@ new BrowserCheck('browse-danube-homepage-v1', {
     'us-east-1',
     'us-west-1',
   ],
-  frequency: 30,
+  frequency: Frequency.EVERY_30M,
   // what must happen to generate an alert
   alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
     amount: 0,
@@ -397,7 +397,7 @@ export const slackChannel = new SlackAppAlertChannel('slack-channel-1', {
 Now we can go back to our URL monitor from part 1 and update it to include multiple alert channels:
 
 ```ts {tile="url-monitor.check.ts"}
-import { UrlAssertionBuilder, UrlMonitor } from 'checkly/constructs'
+import { Frequency, UrlAssertionBuilder, UrlMonitor } from 'checkly/constructs'
 import { emailChannel } from './email-alert-channel'
 import { slackChannel } from './slack-alert-channel'
 import { webhookChannel } from './webhook-alert-channel'
@@ -405,7 +405,7 @@ import { webhookChannel } from './webhook-alert-channel'
 new UrlMonitor('url-monitor-example', {
   name: 'Example URL Monitor',
   activated: true,
-  frequency: 1,
+  frequency: Frequency.EVERY_1M,
   maxResponseTime: 10000,
   degradedResponseTime: 5000,
   alertChannels: [emailChannel, slackChannel, webhookChannel], // Array of alert channels to notify when check fails or recovers
diff --git a/platform/manage-secrets-at-scale.mdx b/platform/manage-secrets-at-scale.mdx
index ab4be687..f9d3cb22 100644
--- a/platform/manage-secrets-at-scale.mdx
+++ b/platform/manage-secrets-at-scale.mdx
@@ -108,14 +108,14 @@ new ApiCheck('payments-health', {
 Define a secret directly on the check when no other check needs it:
 
 ```typescript __checks__/payments-admin.check.ts
-import { ApiCheck } from 'checkly/constructs'
+import { Frequency, ApiCheck } from 'checkly/constructs'
 import { PAYMENTS_ADMIN_TOKEN } from '../secrets'
 
 new ApiCheck('payments-admin-health', {
   name: 'Payments admin health',
   activated: true,
   muted: false,
-  frequency: 10,
+  frequency: Frequency.EVERY_10M,
   locations: ['us-east-1'],
   environmentVariables: [
     {

From e070e2cc2b833724beb83416a78cb72d104719ee Mon Sep 17 00:00:00 2001
From: Simo Kinnunen <simo@checklyhq.com>
Date: Fri, 4 Sep 2026 21:57:44 +0900
Subject: [PATCH 6/8] docs: import from the checkly package instead of the old
 @checkly/cli name [RED-935]

Three pages still imported constructs from `@checkly/cli`, the package
name the CLI shipped under before it was renamed to `checkly`. Bringing
those blocks under the type check also surfaced a lowercase retry
strategy type (`'linear'`, the API takes `'LINEAR'`) and a mis-cased
`./alert-Channels` import, and a browser check block titled as the
config file. The `@checkly/cli-nodejs` auth.json paths on the login and
logout pages are unchanged: the CLI still stores its config under that
name.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../api-checks/setup-and-teardown.mdx              |  2 +-
 detect/testing/creating-your-first-test.mdx        | 13 ++++++-------
 .../monitoring-ecommerce-apps-using-playwright.mdx | 14 +++++++-------
 3 files changed, 14 insertions(+), 15 deletions(-)

diff --git a/detect/synthetic-monitoring/api-checks/setup-and-teardown.mdx b/detect/synthetic-monitoring/api-checks/setup-and-teardown.mdx
index b2cff679..bfef1711 100644
--- a/detect/synthetic-monitoring/api-checks/setup-and-teardown.mdx
+++ b/detect/synthetic-monitoring/api-checks/setup-and-teardown.mdx
@@ -98,7 +98,7 @@ Your folder structure:
 The API check performs a `GET` on an authenticated endpoint:
 
 ```ts api.check.ts
-import { ApiCheck } from '@checkly/cli/constructs'
+import { ApiCheck } from 'checkly/constructs'
 import * as path from 'path'
 
 new ApiCheck('api-check-1', {
diff --git a/detect/testing/creating-your-first-test.mdx b/detect/testing/creating-your-first-test.mdx
index 22d965c7..cec2774a 100644
--- a/detect/testing/creating-your-first-test.mdx
+++ b/detect/testing/creating-your-first-test.mdx
@@ -54,9 +54,9 @@ my-checkly-project/
 
 Open `checkly.config.ts` to configure your monitoring setup:
 
-```ts Checkly.config.ts
-import { defineConfig } from '@checkly/cli'
-import { Frequency } from '@checkly/cli/constructs'
+```ts checkly.config.ts
+import { defineConfig } from 'checkly'
+import { Frequency } from 'checkly/constructs'
 
 export default defineConfig({
   projectName: 'My First Checkly Project',
@@ -147,9 +147,8 @@ After deployment, you can:
 
 For more control over your browser checks:
 
-```ts Checkly.config.ts
-// __checks__/advanced-browser.check.ts
-import { BrowserCheck, Frequency } from '@checkly/cli/constructs'
+```ts __checks__/advanced-browser.check.ts
+import { BrowserCheck, Frequency } from 'checkly/constructs'
 
 new BrowserCheck('advanced-check', {
   name: 'Advanced Browser Check',
@@ -161,7 +160,7 @@ new BrowserCheck('advanced-check', {
     entrypoint: './advanced-test.spec.ts',
   },
   retryStrategy: {
-    type: 'linear',
+    type: 'LINEAR',
     baseBackoffSeconds: 60,
     maxRetries: 2,
   },
diff --git a/guides/monitoring-ecommerce-apps-using-playwright.mdx b/guides/monitoring-ecommerce-apps-using-playwright.mdx
index f93b5354..7b4b73ac 100644
--- a/guides/monitoring-ecommerce-apps-using-playwright.mdx
+++ b/guides/monitoring-ecommerce-apps-using-playwright.mdx
@@ -196,8 +196,8 @@ Next up, we want to create our `checkly.config.ts` file and include the basic Ch
 <Tabs>
 <Tab title="checkly.config.ts">
 ```ts checkly.config.ts
-import { defineConfig } from '@checkly/cli'
-import { Frequency } from '@checkly/cli/constructs'
+import { defineConfig } from 'checkly'
+import { Frequency } from 'checkly/constructs'
 
 export default defineConfig({
  projectName: 'Website Monitoring',
@@ -237,7 +237,7 @@ $ npx checkly login
 ? Do you allow to open the browser to continue with login? Yes
 ? Which account do you want to use? TestCheckly
 Successfully logged in as Hannes Lenke
-Welcome to @checkly/cli 🦝
+Welcome to the Checkly CLI
 ```
 
 Now it's time to test run your browser checks on Checkly:
@@ -286,7 +286,7 @@ Browser Checks are now there to keep us informed on the status of our key websit
 <Tab title="API check resource">
 ```ts api.check.ts
 // __check__/api.check.ts
-import { Frequency, ApiCheck, AssertionBuilder } from '@checkly/cli/constructs'
+import { Frequency, ApiCheck, AssertionBuilder } from 'checkly/constructs'
 
 const api = new ApiCheck('webstore-list-books', {
   name: 'List Books API',
@@ -317,7 +317,7 @@ Now that we have our Checks in place, we want to set up alerting to ensure we ar
 
 ```ts alert-channels.ts
 // alert-channels.ts
-import { EmailAlertChannel } from '@checkly/cli/constructs'
+import { EmailAlertChannel } from 'checkly/constructs'
 
 const sendDefaults = {
   sendFailure: true,
@@ -335,8 +335,8 @@ We are setting up things so that we are alerted when our Check starts failing, a
 
 ```ts api.check.ts
 // __check__/api.check.ts
-import { Frequency, ApiCheck, AssertionBuilder } from '@checkly/cli/constructs'
-import { emailChannel } from './alert-Channels'
+import { Frequency, ApiCheck, AssertionBuilder } from 'checkly/constructs'
+import { emailChannel } from './alert-channels'
 
 const api = new ApiCheck('webstore-list-books', {
   name: 'List Books API',

From 544991fc66632663fe74654c1ea1e075921cf07a Mon Sep 17 00:00:00 2001
From: Simo Kinnunen <simo@checklyhq.com>
Date: Fri, 4 Sep 2026 22:05:15 +0900
Subject: [PATCH 7/8] docs: correct where the CLI stores its auth file
 [RED-935]

The login and logout pages pointed at `@checkly/cli-nodejs`, but the CLI
registers its config store with an explicit empty suffix, so the real
directory is `@checkly/cli` (`Config` subfolder on Windows). The login
page also described the tokens as encrypted; the store has no encryption
key and the file is plain JSON.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 cli/checkly-login.mdx  | 8 ++++----
 cli/checkly-logout.mdx | 8 +++++---
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/cli/checkly-login.mdx b/cli/checkly-login.mdx
index a5afb7d4..323f66a1 100644
--- a/cli/checkly-login.mdx
+++ b/cli/checkly-login.mdx
@@ -71,11 +71,11 @@ If you already have an account:
 
 After successful login, the CLI stores authentication tokens locally in:
 
-- **macOS**: `~/Library/Preferences/@checkly/cli-nodejs/auth.json`
-- **Linux**: ` ~/.config/@checkly/cli-nodejs/auth.json`
-- **Windows**: `%APPDATA%\@checkly\cli-nodejs\auth.json`
+- **macOS**: `~/Library/Preferences/@checkly/cli/auth.json`
+- **Linux**: `~/.config/@checkly/cli/auth.json`
+- **Windows**: `%APPDATA%\@checkly\cli\Config\auth.json`
 
-These tokens are encrypted and used for subsequent CLI operations without requiring re-authentication.
+The file is plain JSON and is not encrypted. The stored tokens are used for subsequent CLI operations without requiring re-authentication.
 
 ## Troubleshooting
 
diff --git a/cli/checkly-logout.mdx b/cli/checkly-logout.mdx
index 06059834..22f569f8 100644
--- a/cli/checkly-logout.mdx
+++ b/cli/checkly-logout.mdx
@@ -65,9 +65,11 @@ The logout process will:
 
 The command removes authentication tokens stored locally in:
 
-- **macOS**: `~/Library/Preferences/@checkly/cli-nodejs/auth.json`
-- **Linux**: `~/.config/@checkly/cli-nodejs/auth.json`
-- **Windows**: `%APPDATA%\@checkly\cli-nodejs\auth.json`
+- **macOS**: `~/Library/Preferences/@checkly/cli/auth.json`
+- **Linux**: `~/.config/@checkly/cli/auth.json`
+- **Windows**: `%APPDATA%\@checkly\cli\Config\auth.json`
+
+The same directory holds a `config.json` with the selected account ID and name, which is cleared as well.
 
 ## After Logout
 

From ae9ce50580a4eb36dfbd40a3304db355993f7e1f Mon Sep 17 00:00:00 2001
From: Simo Kinnunen <simo@checklyhq.com>
Date: Fri, 4 Sep 2026 22:10:30 +0900
Subject: [PATCH 8/8] docs: use the construct builders instead of hand-built
 objects [RED-935]

Hand-written retry strategy and alert escalation objects are easy to get
wrong (casing of enum values, REST-API field names that the constructs
do not accept). Switch the remaining samples to RetryStrategyBuilder and
AlertEscalationBuilder. The startup guide showed an `alertSettings`
object in the REST API's shape, which is not a construct property; it
now shows `alertEscalationPolicy` built with the builder. Also correct
`comparison: 'lessThan'` to `'LESS_THAN'` in an explanatory comment.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 constructs/url-monitor.mdx                    |  2 +-
 detect/testing/creating-your-first-test.mdx   |  7 +++---
 guides/create-multiple-monitors.mdx           |  7 +++---
 ...artup-guide-detect-communicate-resolve.mdx | 25 ++++++++-----------
 4 files changed, 18 insertions(+), 23 deletions(-)

diff --git a/constructs/url-monitor.mdx b/constructs/url-monitor.mdx
index 816c4b6d..4280ba61 100644
--- a/constructs/url-monitor.mdx
+++ b/constructs/url-monitor.mdx
@@ -253,7 +253,7 @@ UrlAssertionBuilder.statusCode().equals(200)
 ```ts
 UrlAssertionBuilder.statusCode().lessThan(300)
 // Equivalent to:
-{ source: 'STATUS_CODE', comparison: 'lessThan', target: '300' }
+{ source: 'STATUS_CODE', comparison: 'LESS_THAN', target: '300' }
 ```
 
 Learn more in our docs on [Assertions](/detect/assertions).
diff --git a/detect/testing/creating-your-first-test.mdx b/detect/testing/creating-your-first-test.mdx
index cec2774a..39775c6d 100644
--- a/detect/testing/creating-your-first-test.mdx
+++ b/detect/testing/creating-your-first-test.mdx
@@ -148,7 +148,7 @@ After deployment, you can:
 For more control over your browser checks:
 
 ```ts __checks__/advanced-browser.check.ts
-import { BrowserCheck, Frequency } from 'checkly/constructs'
+import { BrowserCheck, Frequency, RetryStrategyBuilder } from 'checkly/constructs'
 
 new BrowserCheck('advanced-check', {
   name: 'Advanced Browser Check',
@@ -159,11 +159,10 @@ new BrowserCheck('advanced-check', {
   code: {
     entrypoint: './advanced-test.spec.ts',
   },
-  retryStrategy: {
-    type: 'LINEAR',
+  retryStrategy: RetryStrategyBuilder.linearStrategy({
     baseBackoffSeconds: 60,
     maxRetries: 2,
-  },
+  }),
 })
 ```
 
diff --git a/guides/create-multiple-monitors.mdx b/guides/create-multiple-monitors.mdx
index d9e1cffb..ea0e5ca7 100644
--- a/guides/create-multiple-monitors.mdx
+++ b/guides/create-multiple-monitors.mdx
@@ -242,7 +242,7 @@ As you handle monitors for multiple sites and environments, inevitably you'll wa
 We can create a group with constructs:
 
 ```ts {title="prod-monitoring-group.ts"}
-import { Frequency, CheckGroupV2 } from 'checkly/constructs'
+import { Frequency, CheckGroupV2, RetryStrategyBuilder } from 'checkly/constructs'
 
 export const prodMonitorGroup = new CheckGroupV2('prod-monitor-group', {
   name: 'Prod Monitor Group',
@@ -251,13 +251,12 @@ export const prodMonitorGroup = new CheckGroupV2('prod-monitor-group', {
   locations: ['us-east-1', 'eu-west-1'],
   tags: ['url-monitoring', 'production'],
   environmentVariables: [],
-  retryStrategy: {
-    type: 'FIXED',
+  retryStrategy: RetryStrategyBuilder.fixedStrategy({
     baseBackoffSeconds: 60,
     maxRetries: 2,
     maxDurationSeconds: 600,
     sameRegion: false
-  }
+  })
 })
 ```
 
diff --git a/guides/startup-guide-detect-communicate-resolve.mdx b/guides/startup-guide-detect-communicate-resolve.mdx
index cbba0f3b..5549bf77 100644
--- a/guides/startup-guide-detect-communicate-resolve.mdx
+++ b/guides/startup-guide-detect-communicate-resolve.mdx
@@ -346,22 +346,19 @@ Now that issues have been detected with proactive monitoring, we need to plan ho
 
 ### Configure When Alerts Go Out
 
-By setting up alert rules, you can define conditions—such as consecutive failures or specific error responses—that trigger alerts.  You can also configure how to handle retries before generating an alert, and whether reminder messages go out for an ongoing alert.  This is particularly useful for handling transient network issues or brief API hiccups. Well-tuned alerting policies allow your DevOps or SRE team to quickly identify and investigate issues before they escalate, without burdening the team with many false alarms. All of these settings are covered in the `alertSettings` portion of the construct for any monitor.
+By setting up alert rules, you can define conditions—such as consecutive failures or specific error responses—that trigger alerts.  You can also configure how to handle retries before generating an alert, and whether reminder messages go out for an ongoing alert.  This is particularly useful for handling transient network issues or brief API hiccups. Well-tuned alerting policies allow your DevOps or SRE team to quickly identify and investigate issues before they escalate, without burdening the team with many false alarms. All of these settings are covered by the `alertEscalationPolicy` property of any monitor construct. Build it with [`AlertEscalationBuilder`](/constructs/alert-escalation-policy) rather than writing the object by hand:
 
 ```ts
-alertSettings: {
-  reminders: { // Controls reminder notifications after initial alert
-    amount: 0, // Number of reminder notifications to send (0 = no reminders)
-    interval: 5 // Time interval in minutes between each reminder notification
-  },
-  escalationType: "RUN_BASED", // Sets escalation trigger type (RUN_BASED or TIME_BASED)
-  runBasedEscalation: { // Configuration for run-based escalation triggers
-    failedRunThreshold: 1 // Number of consecutive failed runs before escalating alert
-  },
-  timeBasedEscalation: { // Configuration for time-based escalation triggers
-    minutesFailingThreshold: 5 // Minutes check must be failing before escalating alert
-  }
-}
+import { AlertEscalationBuilder } from 'checkly/constructs'
+
+// Escalate after 1 consecutive failed run; send no reminders
+alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(1, {
+  amount: 0, // Number of reminder notifications to send (0 = no reminders)
+  interval: 5, // Minutes between reminder notifications
+})
+
+// Or escalate once the check has been failing for 5 minutes
+alertEscalationPolicy: AlertEscalationBuilder.timeBasedEscalation(5)
 ```
 
 These settings just like all the settings in this section can be managed at the individual check level, [as a group](/platform/groups), or across the whole project in the `checkly.config.ts` file.