feat: add Entitlements group troubleshoot guide [TREE-202 TREE-77]

site/content/docs/alerting-and-retries/retries.md

@@ -28,14 +28,15 @@ Click **Edit check** or **Edit group** on the 3-dot menu on your [Checkly Home p
 
 There are three distinct retry strategies based on the time between retry attempts, and each one comes with different retry/backoff characteristics.
 
+- **Retry once** — a single retry after a fixed interval, e.g. 5s.
 - **Fixed** — a fixed time between retries, e.g. 5s, 5s, 5s etc.
 - **Linear** — a linearly increasing time between retries, e.g. 5s, 10s, 15s etc.
 - **Exponential** — an exponentially increasing time between retries, e.g. 5s, 25s, 125s (2m and 5s)  etc.
 
 On top of the time between attempts, you can also set:
 
-* **maximum number of retries** - the maximum number of retries for this check or check group.
-* **maximum total retry duration** - the maximum time a check can be in a retrying state.
+- **maximum number of retries** - the maximum number of retries for this check or check group.
+- **maximum total retry duration** - the maximum time a check can be in a retrying state.
 This is a timeout to ensure the check finishes on a timely manner.
 
 > Make sure to include the time your check needs to run when setting the **maximum total retry duration**. For example, if you set a maximum to 2 minutes, and your check takes 1.5 minutes, you have 30 seconds left for retries.
@@ -57,8 +58,8 @@ Of course, picking the right strategy depends on your use case, tolerance for in
 
 ### Location-based check retries
 
-You can decide if a check should be retried from the same location or not with the checkbox: 
-**Always retry from the same location the check failed in**
+You can decide if a check should be retried from the same location or not with the checkbox "**Always retry from the same location the check failed in**":
+
 - If enabled, a check that fails will be retried in the same location. 
 - If disabled, a check that fails will be retried in a different location, from the locations your check runs at.
 
@@ -72,8 +73,9 @@ There are some tradeoffs to consider:
 For API checks & URL monitors, you can enable network retries to automatically retry a check run only if it fails due to a network error—such as a timeout, DNS resolution issue, or connection reset.
 
 When network retries are enabled:
-* The check will retry on: ECONNRESET, ENOTFOUND, ETIMEDOUT, EAI_AGAIN, ECONNREFUSED, and similar network errors.
-* The check will not retry on: Any HTTP response that includes a status code (4xx or 5xx), failed assertions, or any other type of check failure.
+
+- The check will retry on: `ECONNRESET`, `ENOTFOUND`, `ETIMEDOUT`, `EAI_AGAIN`, `ECONNREFUSED`, and similar network errors.
+- The check will not retry on: Any HTTP response that includes a status code (4xx or 5xx), failed assertions, or any other type of check failure.
 
 ## Test sessions retries
 
@@ -112,6 +114,7 @@ All retry attempts are be visible on the web interface at Checkly and in your co
 ```
 
 ### Test session retries in your CI/CD pipeline
+
 Use the ``--reporter=ci`` flag to run test session retries from your CI/CD pipeline. The `ci` reporter will print out all retry attempts in the prompt output, instead of live-updating the prompt. 
 
 For example: 

site/content/docs/cli/constructs-reference.md

@@ -474,7 +474,7 @@ Use the CheckGroupV2 construct to organize your Checks into groups. This comes w
 
 > Note: you will notice that managing shared configuration between Checks is very easy just using JS/TS. You might not need Check Groups for that purpose.
 
-#### Adding Checks to a Check Group
+### Adding Checks to a Check Group
 
 You can add a Check to a group in two ways.
 
@@ -533,6 +533,12 @@ new ApiCheck('check-group-api-check-1', {
 > Note that you can configure two different `frequency` properties for API and Browser checks in a `CheckGroup` separately.
 > The CLI follows a fallback logic using `Check->CheckGroup->Project` configurations.
 
+### How overrides work for mixed groups
+
+Group validation ensures that all checks within a group can support the selected configuration settings. Since uptime monitors and synthetic checks have different feature limitations based on your plan tier, Checkly validates group settings against the lowest common denominator of supported features to prevent configuration conflicts.
+
+For detailed guidance, see [Mixing Different Monitor Types in a Group](/docs/groups/#mixing-different-monitor-types-in-a-group).
+
 ## `CheckGroup` (deprecated)
 
 As of CLI release v6.0 the CheckGroup construct is deprecated and will be removed in a future version. We recommend migrating to [CheckGroupV2](#checkgroupv2), which offers more intuitive behavior and better control.
@@ -1051,7 +1057,7 @@ new ApiCheck('local-api-1', {
 ## `RetryStrategy`
 
 `RetryStrategy` objects can be used to configure retries for failed check runs.
-Retry strategies can be set at the [check](#check), [check group](#checkgroup), and [project](#project) levels.
+Retry strategies can be set at the [check](#synthetic-checks) and [monitor](#uptime-monitors), [check group](#checkgroupv2), and [project](#project) levels.
 [Learn more about retry strategies](/docs/alerting-and-retries/retries/#retry-strategies).
 
 To build `RetryStrategy` objects you should use the `RetryStrategyBuilder`, which provides helper methods for configuring retries.
@@ -1077,6 +1083,7 @@ new ApiCheck('retrying-check', {
 `RetryStrategyBuilder` supports the following helper methods:
 
 - `noRetries()`: No retries are performed.
+- `singleStrategy(options)`: A single retry is performed after a fixed interval, e.g. 5s
 - `fixedStrategy(options)`: A fixed time between retries, e.g. 5s, 5s, 5s etc.
 - `linearStrategy(options)`: A linearly increasing time between retries, e.g. 5s, 10s, 15s, etc.
 - `exponentialStrategy(options)`: An exponentially increasing time between retries, e.g. 5s, 25s, 125s (2m and 5s) etc.

site/content/docs/groups/_index.md

@@ -17,7 +17,7 @@ Groups help you organize your checks (e.g. by team or feature) and apply shared
 
 ![Check group screenshot](/docs/images/groups/group-in-dashboard.png)
 
-# Creating a check group
+## Creating a check group
 
 By default, newly created check groups behave like folders, with no [group-level configuration](#group-level-configuration) applied. To get started:
 
@@ -27,14 +27,16 @@ By default, newly created check groups behave like folders, with no [group-level
 
 You can populate a group by moving existing checks into it or by creating new checks directly within the group.
 
-# Group level configuration
+## Group level configuration
 
 Groups let you apply shared configuration to standardize how checks behave. Below is a breakdown of each setting and how it affects checks in the group:
 
 ### API checks defaults
+
 You can define [API check defaults](/docs/groups/api-check-defaults/) such as a common base URL, request information, [assertions](/docs/api-checks/assertions/), and [setup & teardown scripts](/docs/api-checks/setup-teardown-scripts/) to manage API checks in your group at scale.
 
 ### Variables
+
 For configuration information commonly used by checks in your group, create [group environment variables and secrets](/docs/groups/variables/). These are merged with variables at the global and check levels when a check runs.
 
 ### Scheduling & locations overrides
@@ -62,7 +64,7 @@ You can run checks in this group as [E2E tests](/docs/testing) locally or from y
 
 Checkly manages the [runtime](/docs/runtimes) environment for your JavaScript code in browser checks and setup & teardown scripts. If the checks in this group need a runtime different from your account default, you can set that here.
 
-# Adding or removing checks from groups
+## Adding or removing checks from groups
 
 * **Moving a check into a group:** If the group has [group-level configuration](#group-level-configuration) defined, adding a check may change how it runs. Settings like API defaults, locations & scheduling, or retries & alerting can override or append to the check’s configuration.
 
@@ -71,7 +73,7 @@ Checkly manages the [runtime](/docs/runtimes) environment for your JavaScript co
 > [!WARNING]
 > To prevent issues (e.g. broken references to group variables), the check will be automatically deactivated after being added to or removed from a group. Make sure to review its settings before reactivating.
 
-# How we run grouped checks
+## How we run grouped checks
 
 It helps to understand how we run the checks in a group, specifically if you're doing more sophisticated checks with shared
 variables, script and alerting channels. Here are the rules:
@@ -82,5 +84,19 @@ variables, script and alerting channels. Here are the rules:
 4. There are no results or metrics collected at the group level.
 5. Checks in a group still have their individual scheduling settings.
 
-As you can see, groups in their current incarnation are mostly handy configuration buckets for common properties. In the 
-future we will expand the group features to make them smarter.
+As you can see, groups in their current incarnation are mostly handy configuration buckets for common properties. In the future we will expand the group features to make them smarter.
+
+## Mixing Different Monitor Types in a Group
+
+When you purchase a plan in Checkly, it comes with certain feature entitlements, which you can review on our [pricing page](https://www.checklyhq.com/pricing/). These entitlements differ by monitor type:
+
+* Synthetic checks (e.g. API, Multistep, Browser, Playwright Check Suites)
+* Uptime monitors (e.g. URL, TCP, DNS)
+
+This means checks and monitors on the same plan may not all have access to the same features. For example: An API check might support `parallel` scheduling, while a TCP monitor only allows for `round-robin` scheduling.
+
+Groups let you organize any type of checks/monitors together and define shared settings. If those shared settings aren’t supported by all monitors in the group, Checkly will throw a validation error asking you to either adjust the setting or remove the incompatible monitor.
+
+Example: If your plan only allows `round-robin` for uptime monitors and you configure the group with `parallel` scheduling, you’ll see an error. To resolve it, switch to `round-robin`, move uptime monitors into a separate group, or upgrade your plan.
+
+If you’re unsure how to proceed, don’t hesitate to reach out to our [support team](mailto:support@checklyhq.com), we’re happy to help.