Edit max_signals field for custom rules in UI [classic] (#5106)

* First draft

* Update docs/detections/rules-ui-create.asciidoc

* Revise note (in API docs too)

* Update ESQL rule steps

per elastic/staging-serverless-security-docs#340 (comment)

* Revise alert suppression refs to max_signals

* Explain max_signals = Max alerts per run

* Add updates to "update rule" API too

docs/detections/alert-suppression.asciidoc

@@ -113,5 +113,5 @@ image::images/timeline-button.png[Investigate in timeline button, 200]
 
 Some rule types have a maximum number of alerts that can be suppressed (custom query rules don't have a suppression limit):
 
-* **Threshold and event correlation (non-sequence queries only)** - The maximum number of alerts is the value you choose for the <<opt-fields-all,`max_signals`>> setting, which is `100` by default.
-* **Indicator match and new terms** - The maximum number is five times the value you choose for the <<opt-fields-all,`max_signals`>> setting. The default `max_signals` value is `100`, which means the default maximum limit for indicator match rules and new term rules is `500`.
+* **Threshold and event correlation (non-sequence queries only)** - The maximum number of alerts is the value you choose for the rule's **Max alerts per run** <<rule-ui-advanced-params,advanced setting>>, which is `100` by default.
+* **Indicator match and new terms** - The maximum number is five times the value you choose for the rule's **Max alerts per run** <<rule-ui-advanced-params,advanced setting>>. The default value is `100`, which means the default maximum limit for indicator match rules and new term rules is `500`.

docs/detections/api/rules/rules-api-create.asciidoc

@@ -329,9 +329,9 @@ means the rule runs every hour. Defaults to `5m` (5 minutes).
 |license |String |The rule's license.
 
 |max_signals |Integer a|Maximum number of alerts the rule can create during a
-single execution. Defaults to `100`.
+single run (the rule's **Max alerts per run** <<rule-ui-advanced-params,advanced setting>> value). Defaults to `100`.
 
-*NOTE*: To avoid rule failures, do not set the `max_signals` value higher than the value of {kibana-ref}/alert-action-settings-kb.html#alert-settings[`xpack.alerting.rules.run.alerts.max`]. 
+NOTE: This setting can be superseded by the {kibana-ref}/alert-action-settings-kb.html#alert-settings[{kib} configuration setting] `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by _any_ rule in the {kib} alerting framework. For example, if `xpack.alerting.rules.run.alerts.max` is set to `1000`, the rule can generate no more than 1000 alerts even if `max_signals` is set higher.  
 
 |meta |Object a|Placeholder for metadata about the rule.
 

docs/detections/api/rules/rules-api-update.asciidoc

@@ -232,8 +232,10 @@ means the rule runs every hour. Defaults to `5m` (5 minutes).
 
 |license |String |The rule's license.
 
-|max_signals |Integer |Maximum number of alerts the rule can create during a
-single execution. Defaults to `100`.
+|max_signals |Integer a|Maximum number of alerts the rule can create during a
+single run (the rule's **Max alerts per run** <<rule-ui-advanced-params,advanced setting>> value). Defaults to `100`.
+
+NOTE: This setting can be superseded by the {kibana-ref}/alert-action-settings-kb.html#alert-settings[{kib} configuration setting] `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by _any_ rule in the {kib} alerting framework. For example, if `xpack.alerting.rules.run.alerts.max` is set to `1000`, the rule can generate no more than 1000 alerts even if `max_signals` is set higher.  
 
 |meta |Object a|Placeholder for metadata about the rule.
 

docs/detections/rules-ui-create.asciidoc

@@ -435,11 +435,9 @@ FROM logs-* METADATA _id, _index, _version
 
 When writing your query, consider the following:
 
-- The {ref}/esql-commands.html#esql-limit[`LIMIT`] command specifies the maximum number of rows an {esql} query returns and the maximum number of alerts created per rule execution. Similarly, a detection rule's <<opt-fields-all,`max_signals`>> setting specifies the maximum number of alerts it can create every time it runs.
+- The {ref}/esql-commands.html#esql-limit[`LIMIT`] command specifies the maximum number of rows an {esql} query returns and the maximum number of alerts created per rule execution. Similarly, a detection rule's **Max alerts per run** setting specifies the maximum number of alerts it can create every time it runs.
 + 
-If the `LIMIT` value is lower than the `max_signals` value, the rule uses the `LIMIT` value to determine the maximum number of alerts the rule generates. If the `LIMIT` value is higher than the `max_signals` value, the rule uses the `max_signals` value. 
-+
-NOTE: The `max_signals` default value is 100. You can modify it using the <<rules-api-create,Create rule API>>. 
+If the `LIMIT` value and **Max alerts per run** value are different, the rule uses the lower value to determine the maximum number of alerts the rule generates. 
 +
 
 - When writing an aggregating query, use the {ref}/esql-commands.html#esql-stats-by[`STATS...BY`] command with fields that you want to search and filter for after alerts are created. For example, using the `host.name`, `user.name`, `process.name` fields with the `BY` operator of the `STATS...BY` command returns these fields in alert documents, and allows you to search and filter for them from the Alerts table. 
@@ -534,6 +532,10 @@ also affect this rule.
 .. *Building block* (optional): Select to create a building-block rule. By
 default, alerts generated from a building-block rule are not displayed in the
 UI. See <<building-block-rule>> for more information.
+.. **Max alerts per run** (optional): Specify the maximum number of alerts the rule can create each time it runs. Default is 100.
++
+NOTE: This setting can be superseded by the {kibana-ref}/alert-action-settings-kb.html#alert-settings[{kib} configuration setting] `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by _any_ rule in the {kib} alerting framework. For example, if `xpack.alerting.rules.run.alerts.max` is set to `1000`, the rule can generate no more than 1000 alerts even if **Max alerts per run** is set higher.
+
 .. *Indicator prefix override*: Define the location of indicator data within the structure of indicator documents. When the indicator match rule executes, it queries specified indicator indices and references this setting to locate fields with indicator data. This data is used to enrich indicator match alerts with metadata about matched threat indicators. The default value for this setting is `threat.indicator`.
 +
 IMPORTANT: If your threat indicator data is at a different location, update this setting accordingly to ensure alert enrichment can still be performed.