[Ruleset Engine] Doc improvements based on assessment (#25958)

Author: pedrosousa

src/content/docs/cache/how-to/cache-rules/create-api.mdx

@@ -12,7 +12,7 @@ head:
 
 import { Details, APIRequest } from "~/components"
 
-Use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/rulesets-api/) to create a cache rule via API. To configure Cloudflare’s API refer to the [API documentation](/fundamentals/api/get-started/).
+Use the [Rulesets API](/ruleset-engine/rulesets-api/) to create a cache rule via API. To configure Cloudflare’s API refer to the [API documentation](/fundamentals/api/get-started/).
 
 ## Basic rule settings
 

src/content/docs/ruleset-engine/about/phases.mdx

@@ -3,21 +3,16 @@ title: Phases
 pcx_content_type: concept
 sidebar:
   order: 2
-
 ---
 
-A phase defines a stage in the life of a request where you can execute rulesets. Phases are defined by Cloudflare and cannot be modified.
+A phase defines a stage in the life of a request where you can execute [rulesets](/ruleset-engine/about/rulesets/). Phases are defined by Cloudflare and cannot be modified.
 
-Phases exist at two levels: at the **account** level and at the **zone** level. For the same phase, rules defined at the account level are evaluated **before** the rules defined at the zone level.
+Phases exist at two levels: at the account level and at the zone level. For the same phase, rules defined at the account level are evaluated before the rules defined at the zone level.
 
 Each phase has at most one [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) at the account and zone level.
 
 :::note
-
-
 Currently, phases at the account level are only available in Enterprise plans.
-
-
 :::
 
 The following diagram outlines the request handling process where requests go through the available phases:

src/content/docs/ruleset-engine/about/rulesets.mdx

@@ -19,7 +19,7 @@ Specific Cloudflare products may provide other types of rulesets.
 
 ## Entry point ruleset
 
-An entry point ruleset contains a list of ordered rules that run in a [phase](/ruleset-engine/about/phases/) at the account or zone level. This ruleset is an entry point for all rules executed in a phase. Some of these rules may run other rulesets.
+An entry point ruleset contains a list of ordered [rules](/ruleset-engine/about/rules/) that run in a [phase](/ruleset-engine/about/phases/) at the account or zone level. This ruleset is an entry point for all rules executed in a phase. Some of these rules may run other rulesets.
 
 Each phase has at most one entry point ruleset at the account level and at the zone level.
 

src/content/docs/ruleset-engine/basic-operations/add-rule-phase-rulesets.mdx

@@ -18,7 +18,7 @@ If you are adding a **single** rule to a ruleset, consider using one of the [rul
 Instead of relying on the automatic creation of an entry point ruleset, you can also create this ruleset explicitly using one of the [ruleset creation operations](/ruleset-engine/rulesets-api/create/).
 :::
 
-<Details header="Example: Set the rules of a phase entry point ruleset at the zone level">
+## Example: Set the rules of a phase entry point ruleset at the zone level
 
 The following example sets the rules of a phase entry point ruleset at the zone level for the `http_request_firewall_managed` phase using the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation.
 
@@ -87,9 +87,7 @@ The following example sets the rules of a phase entry point ruleset at the zone
 }
 ```
 
-</Details>
-
-<Details header="Example: Add a single rule to a phase entry point ruleset at the zone level">
+## Example: Add a single rule to a phase entry point ruleset at the zone level
 
 The following example adds a single rule to a phase entry point ruleset (with ID `$RULESET_ID`) at the zone level using the [Create a zone ruleset rule](/api/resources/rulesets/subresources/rules/methods/create/) operation.
 
@@ -143,5 +141,3 @@ The following example adds a single rule to a phase entry point ruleset (with ID
 	"messages": []
 }
 ```
-
-</Details>

src/content/docs/ruleset-engine/basic-operations/deploy-rulesets.mdx

@@ -6,25 +6,25 @@ sidebar:
   order: 4
 ---
 
-import { APIRequest } from "~/components";
+import { APIRequest, RuleID } from "~/components";
 
 Use the [Rulesets API](/ruleset-engine/rulesets-api/) to deploy a ruleset. To deploy a ruleset, add a rule with `"action": "execute"` to a [phase entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset), specifying the ruleset ID to execute as an action parameter. Use a separate rule for each ruleset you want to deploy.
 
 A rule that executes a ruleset consists of:
 
-- The **ID of the ruleset** you want to execute.
-- An **expression**.
-- An **action**, set to `execute`.
+- The ID of the ruleset you want to execute, included in `action_parameters.id`.
+- An expression.
+- The `execute` action.
 
 The rules in the ruleset execute when a request satisfies the expression.
 
 :::note
-To apply a rule to every request in a phase at the **zone** level, set the rule expression to `true`.
+To apply a rule to every request in a phase at the zone level, set the rule expression to `true`.
 :::
 
 ## Example
 
-The following example deploys a [managed ruleset](/ruleset-engine/about/rulesets/#managed-rulesets) to the `http_request_firewall_managed` phase of a given zone (`$ZONE_ID`) by adding a rule that executes the managed ruleset.
+The following example deploys the [Cloudflare Managed Ruleset](/waf/managed-rules/reference/cloudflare-managed-ruleset/) (with ID <RuleID id="efb7b8c949ac4650a09736fc376e9aee" />) to the `http_request_firewall_managed` phase of a given zone (`$ZONE_ID`) by adding a rule that executes the managed ruleset.
 
 <APIRequest
 	path="/zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint"
@@ -37,7 +37,7 @@ The following example deploys a [managed ruleset](/ruleset-engine/about/rulesets
 			{
 				action: "execute",
 				action_parameters: {
-					id: "<CLOUDFLARE_MANAGED_RULESET_ID>",
+					id: "efb7b8c949ac4650a09736fc376e9aee",
 				},
 				expression: "true",
 				description: "Execute Cloudflare Managed Ruleset on my zone ruleset",
@@ -60,7 +60,7 @@ The following example deploys a [managed ruleset](/ruleset-engine/about/rulesets
 				"version": "1",
 				"action": "execute",
 				"action_parameters": {
-					"id": "<CLOUDFLARE_MANAGED_RULESET_ID>",
+					"id": "efb7b8c949ac4650a09736fc376e9aee",
 					"version": "3"
 				},
 				"expression": "true",
@@ -79,6 +79,10 @@ The following example deploys a [managed ruleset](/ruleset-engine/about/rulesets
 }
 ```
 
+:::caution
+This API request replaces any existing rules in the `http_request_firewall_managed` phase entry point ruleset with a single rule.
+:::
+
 ## Related resources
 
 For more examples of deploying rulesets, refer to the following pages:

src/content/docs/ruleset-engine/basic-operations/view-rulesets.mdx

@@ -10,9 +10,9 @@ import { Details, APIRequest } from "~/components";
 
 ## View available rulesets
 
-You can list the available rulesets for a zone, account, or phase.
+You can list the available rulesets for a zone or account.
 
-<Details header="Example: View available rulesets at the zone level">
+### Example: View available rulesets at the zone level
 
 The response to the `GET` request will include the following rulesets:
 
@@ -22,7 +22,7 @@ The response to the `GET` request will include the following rulesets:
 
 <APIRequest path="/zones/{zone_id}/rulesets" method="GET" />
 
-```json output
+```json output collapse={12-29}
 {
 	"result": [
 		{
@@ -59,9 +59,7 @@ The response to the `GET` request will include the following rulesets:
 }
 ```
 
-</Details>
-
-<Details header="Example: View available rulesets at the account level">
+### Example: View available rulesets at the account level
 
 The response will include the following rulesets:
 
@@ -71,7 +69,7 @@ The response will include the following rulesets:
 
 <APIRequest path="/accounts/{account_id}/rulesets" method="GET" />
 
-```json output
+```json output collapse={12-38}
 {
 	"result": [
 		{
@@ -117,13 +115,11 @@ The response will include the following rulesets:
 }
 ```
 
-</Details>
-
 ## View the rules included in a ruleset
 
 You can view all versions of phase entry points (at the account and zone levels) and custom rulesets, but you can only view the most recent version of managed rulesets.
 
-<Details header="Example: View rules in a phase entry point ruleset at the zone level">
+### Example: View rules in a phase entry point ruleset at the zone level
 
 The following example lists the rules in version `2` of the `http_request_firewall_managed` phase entry point ruleset at the zone level.
 
@@ -165,9 +161,7 @@ The following example lists the rules in version `2` of the `http_request_firewa
 }
 ```
 
-</Details>
-
-<Details header="Example: View rules in a managed ruleset">
+### Example: View rules in a managed ruleset
 
 The following example lists the rules in version `2` of a managed ruleset (the most recent version of that ruleset).
 
@@ -182,7 +176,7 @@ Each rule in a managed ruleset can have associated tags or categories, listed in
 	}}
 />
 
-```json output
+```json output collapse={26-36}
 {
 	"result": {
 		"id": "<MANAGED_RULESET_ID>",
@@ -229,8 +223,6 @@ Each rule in a managed ruleset can have associated tags or categories, listed in
 }
 ```
 
-</Details>
-
 ## Related resources
 
 For more information on the available API methods for viewing rulesets, refer to [List and view rulesets](/ruleset-engine/rulesets-api/view/).

src/content/docs/ruleset-engine/managed-rulesets/override-examples/deploy-cmr-wordpress-block.mdx

@@ -8,20 +8,20 @@ head:
     content: Use tag overrides to set WordPress rules to Block
 ---
 
-import { Details, APIRequest } from "~/components";
+import { Details, APIRequest, Render } from "~/components";
 
 Follow the steps below to create a rule that executes a managed ruleset and defines an override for rules with a specific tag.
 
 1. [Add a rule](/ruleset-engine/basic-operations/deploy-rulesets/) to a phase entry point ruleset that executes a managed ruleset.
 2. [Configure a tag override](/ruleset-engine/managed-rulesets/override-managed-ruleset/) that sets a specified action for all rules with a given tag.
 
-The example below uses the [Update a zone entry point ruleset](/ruleset-engine/rulesets-api/update/) operation to perform the two steps in a single `PUT` request.
+## Zone-level example
+
+This example uses the [Update a zone entry point ruleset](/ruleset-engine/rulesets-api/update/) operation to perform the following two steps in a single `PUT` request:
 
 - Set the list of rules in the `http_request_firewall_managed` phase entry point ruleset to a single rule that executes the [Cloudflare Managed Ruleset](/waf/managed-rules/reference/cloudflare-managed-ruleset/).
 - Override rules with the `wordpress` tag to set the action to `block`. All other rules use the default action provided by the ruleset issuer.
 
-<Details header="Example: Use tag overrides to set WordPress rules to Block at the zone level">
-
 <APIRequest
 	path="/zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint"
 	method="PUT"
@@ -49,9 +49,14 @@ The example below uses the [Update a zone entry point ruleset](/ruleset-engine/r
 	}}
 />
 
-</Details>
+## Account-level example
+
+This example uses the [Update an account entry point ruleset](/ruleset-engine/rulesets-api/update/) operation to perform the following two steps in a single `PUT` request:
 
-<Details header="Example: Use tag overrides to set WordPress rules to Block at the account level">
+- Set the list of rules in the `http_request_firewall_managed` phase entry point ruleset to a single rule that executes the [Cloudflare Managed Ruleset](/waf/managed-rules/reference/cloudflare-managed-ruleset/) for the zone `example.com`.
+- Override rules with the `wordpress` tag to set the action to `block`. All other rules use the default action provided by the ruleset issuer.
+
+<Render file="deploy-account-ruleset-requirement" product="ruleset-engine" />
 
 <APIRequest
 	path="/accounts/{account_id}/rulesets/phases/{ruleset_phase}/entrypoint"
@@ -79,5 +84,3 @@ The example below uses the [Update a zone entry point ruleset](/ruleset-engine/r
 		],
 	}}
 />
-
-</Details>

src/content/docs/ruleset-engine/managed-rulesets/override-examples/enable-selected-rules.mdx

@@ -8,15 +8,15 @@ head:
     content: Use rulesets and rule overrides to only enable selected rules
 ---
 
-import { Details, APIRequest } from "~/components";
+import { Details, APIRequest, Render } from "~/components";
 
 Use a ruleset override and a rule override in a phase entry point ruleset to execute only selected rules in a managed ruleset.
 
 1. [Add a rule](/ruleset-engine/basic-operations/deploy-rulesets/) to a phase entry point ruleset that executes a managed ruleset.
 2. [Configure a ruleset override](/ruleset-engine/managed-rulesets/override-managed-ruleset/) that disables all rules in the managed ruleset.
 3. [Configure a rule override](/ruleset-engine/managed-rulesets/override-managed-ruleset/) to set an action for the rules you want to execute.
 
-<Details header="Example: Configure ruleset and rule overrides at the zone level">
+## Zone-level example
 
 The following `PUT` request uses the [Update a zone entry point ruleset](/ruleset-engine/rulesets-api/update/) operation to define a configuration that executes only two rules from a managed ruleset in the `http_request_firewall_managed` phase.
 
@@ -60,9 +60,7 @@ In this example:
 	}}
 />
 
-</Details>
-
-<Details header="Example: Configure ruleset and rule overrides at the account level">
+## Account-level example
 
 The following `PUT` request uses the [Update an account entry point ruleset](/ruleset-engine/rulesets-api/update/) operation to define a configuration that executes only two rules from a managed ruleset in the `http_request_firewall_managed` phase.
 
@@ -72,6 +70,8 @@ In this example:
 - `"enabled": false` defines an override at the ruleset level to disable all rules in the managed ruleset.
 - `"rules": [{"id": "<RULE_ID_1>", "action": "block", "enabled": true}, {"id": "<RULE_ID_2>", "action": "log", "enabled": true}]` defines a list of overrides at the rule level to enable two individual rules.
 
+<Render file="deploy-account-ruleset-requirement" product="ruleset-engine" />
+
 <APIRequest
 	path="/accounts/{account_id}/rulesets/phases/{ruleset_phase}/entrypoint"
 	method="PUT"
@@ -105,5 +105,3 @@ In this example:
 		],
 	}}
 />
-
-</Details>

src/content/docs/ruleset-engine/managed-rulesets/override-examples/override-ddos-rule-sensitivity.mdx

@@ -12,13 +12,13 @@ Follow the steps below to override the sensitivity of a specific rule of the Clo
 1. [Add a rule](/ruleset-engine/basic-operations/deploy-rulesets/) to a phase to deploy the Cloudflare HTTP DDoS Attack Protection managed ruleset. You only need to deploy this specific ruleset when you wish to define one or more overrides, since it is enabled by default.
 2. [Configure a rule override](/ruleset-engine/managed-rulesets/override-managed-ruleset/) that sets the `sensitivity_level` of a specific rule.
 
+## Example
+
 The following example uses the [Update a zone entry point ruleset](/ruleset-engine/rulesets-api/update/) operation to execute the two steps in a single `PUT` request.
 
 - Set the rules in the `ddos_l7` phase entry point ruleset to a single rule that executes the Cloudflare HTTP DDoS Attack Protection managed ruleset (with ID `<HTTP_DDOS_RULESET_ID>`).
 - Create an override for the rule with ID `<RULE_ID>` and set the rule sensitivity to `low`. All other rules use the default sensitivity defined by Cloudflare.
 
-<Details header="Example: Use an override to set the sensitivity of an HTTP DDoS rule at the zone level">
-
 <APIRequest
 	path="/zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint"
 	method="PUT"
@@ -45,5 +45,3 @@ The following example uses the [Update a zone entry point ruleset](/ruleset-engi
 		],
 	}}
 />
-
-</Details>

src/content/docs/ruleset-engine/managed-rulesets/override-examples/override-ruleset-tag-rule.mdx

@@ -5,7 +5,7 @@ sidebar:
   order: 5
 ---
 
-import { Details, APIRequest } from "~/components";
+import { Details, APIRequest, Render } from "~/components";
 
 Customize the execution of managed rulesets with a combination of ruleset overrides, tag overrides, and rule overrides in your phase entry point ruleset.
 
@@ -14,14 +14,14 @@ Customize the execution of managed rulesets with a combination of ruleset overri
 3. [Configure a tag override](/ruleset-engine/managed-rulesets/override-managed-ruleset/) that sets an action for rules with a given tag.
 4. [Configure a rule override](/ruleset-engine/managed-rulesets/override-managed-ruleset/) that sets an action for the rules you want to execute.
 
-The request below uses the [Update a zone entry point ruleset](/ruleset-engine/rulesets-api/update/) operation to execute the following in a single `PUT` request:
+## Zone-level example
+
+This example uses the [Update a zone entry point ruleset](/ruleset-engine/rulesets-api/update/) operation to execute the following in a single `PUT` request:
 
 - Add a rule to the `http_request_firewall_managed` phase entry point ruleset that executes a managed ruleset.
 - Use category overrides to enable rules with `wordpress` and `drupal` tags and set their actions to `log`.
 - Add a rule override that enables a single rule.
 
-<Details header="Example: Execute a managed ruleset at the zone level with overrides">
-
 In this example:
 
 - `"id": "<MANAGED_RULESET_ID>"` defines the managed ruleset to execute for requests addressed to a zone (`$ZONE_ID`).
@@ -70,9 +70,13 @@ In this example:
 	}}
 />
 
-</Details>
+## Account-level example
 
-<Details header="Example: Execute a managed ruleset at the account level with overrides">
+This example uses the [Update an account entry point ruleset](/ruleset-engine/rulesets-api/update/) operation to execute the following in a single `PUT` request:
+
+- Add a rule to the `http_request_firewall_managed` phase entry point ruleset that executes a managed ruleset for the zone `example.com`.
+- Use category overrides to enable rules with `wordpress` and `drupal` tags and set their actions to `log`.
+- Add a rule override that enables a single rule.
 
 In this example:
 
@@ -81,6 +85,8 @@ In this example:
 - `"categories": [{"category": "wordpress", "action": "log", "enabled": true}, {"category": "drupal", "action": "log", "enabled": true}]` defines an override at the tag level to enable rules tagged with `wordpress` or `drupal` and sets their action to `log`.
 - `"rules": [{"id": "<RULE_ID>", "action": "block", "enabled": true}]` defines an override at the rule level that enables one individual rule and sets the action to `block`.
 
+<Render file="deploy-account-ruleset-requirement" product="ruleset-engine" />
+
 <APIRequest
 	path="/accounts/{account_id}/rulesets/phases/{ruleset_phase}/entrypoint"
 	method="PUT"
@@ -121,5 +127,3 @@ In this example:
 		],
 	}}
 />
-
-</Details>