thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/resources/prompts/ai-assistant/skills/alarms/references/alarm-rules.md

@@ -0,0 +1,795 @@
+# Alarm rules
+
+An alarm rule creates, updates, and clears alarms based on conditions evaluated against an entity's telemetry and attributes. It runs on every telemetry update for any of its argument keys, and re-evaluates on a schedule when the conditions require it (for example, duration-based checks that must re-evaluate over time).
+
+An alarm rule's only output is the alarm record. Reactions to that alarm — sending notifications, running custom logic, calling external APIs, writing to databases — belong to other ThingsBoard features: the notification center reacts to alarm events with notifications, the rule engine reacts with arbitrary server-side actions. That makes alarm rules the prerequisite for those workflows: a request like *"notify me when temperature exceeds 80°C"* decomposes into an alarm rule that fires on the condition plus a notification rule that delivers the message. Build the alarm rule here and point the user to the relevant downstream feature for the rest — do not dismiss the broader request. An alarm rule is the wrong tool only when no alarm is involved at all (for example, a prediction or analytics computation with no triggering event).
+
+## Constraints
+
+- A rule must have at least one trigger condition. Each severity can appear in at most one trigger condition.
+- Supported argument types: `TS_LATEST` and `ATTRIBUTE` only. Rolling time-series windows are not supported.
+- The argument name must start with a letter or underscore and contain only letters, digits, and underscores.
+- The `missing for` predicate (the no-data check) is available only in **Simple** mode (filters), not in **Script** mode (TBEL).
+- Script-mode conditions use TBEL (ThingsBoard Expression Language). JavaScript is not supported.
+- A clear condition is optional. Without one, alarms can only be cleared manually.
+
+## Configuration shape
+
+```json
+{
+  "name": "<alarm type>",
+  "entityId": { "entityType": "<DEVICE_PROFILE | ASSET_PROFILE | DEVICE | ASSET | CUSTOMER>", "id": "<host UUID>" },
+  "debugSettings": { "...": "see Debug mode below" },
+  "configuration": {
+    "type": "ALARM",
+    "arguments": {
+      "<argName>": { "...": "see Arguments below" }
+    },
+    "createRules": {
+      "<SEVERITY>": {
+        "condition": { "...": "see Trigger conditions below" },
+        "alarmDetails": "<text or null>",
+        "dashboardId": { "entityType": "DASHBOARD", "id": "<UUID>" }
+      }
+    },
+    "clearRule": {
+      "condition": { "...": "see Clear condition below" },
+      "alarmDetails": "<text or null>",
+      "dashboardId": { "entityType": "DASHBOARD", "id": "<UUID>" }
+    },
+    "propagate": false,
+    "propagateToOwner": false,
+    "propagateToOwnerHierarchy": false,
+    "propagateToTenant": false,
+    "propagateRelationTypes": []
+  }
+}
+```
+
+Severity keys for `createRules`: `CRITICAL`, `MAJOR`, `MINOR`, `WARNING`, `INDETERMINATE`.
+
+`alarmDetails` and `dashboardId` are optional (`null` or absent when not set).
+
+`clearRule` may be `null` or absent when no automatic clear is configured.
+
+## General
+
+### Host entity
+
+Every alarm rule is created on a single **host entity**, which determines where the rule appears and which entities it runs on:
+
+- **Profile host** (`DEVICE_PROFILE`, `ASSET_PROFILE`) — the rule applies to every device or asset using that profile. Each such entity is the originator of its own alarms; the profile entity is not the originator.
+- **Specific entity host** (`DEVICE`, `ASSET`, `CUSTOMER`) — the rule applies only to that single entity, which is the originator of its alarms.
+
+The term **current entity** refers to the specific entity the rule is evaluating against at any given moment.
+
+### Alarm type
+
+The rule's `name` becomes the `type` field on every alarm it creates. Pick a name that describes the kind of problem (e.g., *High Temperature*, *Low Battery*); users sometimes call this the rule's *title*. The type field controls alarm de-duplication and severity escalation — see SKILL.md for details.
+
+## Arguments
+
+Arguments declare which telemetry and attribute keys the rule reads. Any key referenced in a condition or in a `${...}` placeholder must first be declared as an argument.
+
+```json
+"<argName>": {
+  "refEntityId": { "entityType": "<DEVICE | ASSET | CUSTOMER | TENANT>", "id": "<UUID>" },
+  "refDynamicSourceConfiguration": { "type": "CURRENT_OWNER" },
+  "refEntityKey": {
+    "type": "<TS_LATEST | ATTRIBUTE>",
+    "key": "<key name>",
+    "scope": "<CLIENT_SCOPE | SERVER_SCOPE | SHARED_SCOPE — only for ATTRIBUTE>"
+  },
+  "defaultValue": "<optional fallback when the referenced key has no value>"
+}
+```
+
+### Target entity
+
+The target entity says which entity the argument reads its value from. Use exactly one of these per argument, or omit both `refEntityId` and `refDynamicSourceConfiguration` for the current entity:
+
+| Argument source   | Argument JSON fields                                                                                   |
+|-------------------|--------------------------------------------------------------------------------------------------------|
+| current entity    | omit both `refEntityId` and `refDynamicSourceConfiguration`                                            |
+| current tenant    | `"refEntityId": { "entityType": "TENANT", "id": "13814000-1dd2-11b2-8080-808080808080" }` — any valid UUID; the tool overrides it with the real tenant ID |
+| current owner     | `"refDynamicSourceConfiguration": { "type": "CURRENT_OWNER" }`                                         |
+| specific device   | `"refEntityId": { "entityType": "DEVICE", "id": "<UUID>" }`                                            |
+| specific asset    | `"refEntityId": { "entityType": "ASSET", "id": "<UUID>" }`                                             |
+| specific customer | `"refEntityId": { "entityType": "CUSTOMER", "id": "<UUID>" }`                                          |
+
+### Argument type
+
+The argument type determines what kind of data the argument reads:
+
+- **Latest telemetry** — the most recent value of a time series key. Set `refEntityKey.type` to `TS_LATEST`.
+- **Attribute** — the value of an attribute key. Set `refEntityKey.type` to `ATTRIBUTE` and add `scope` (`CLIENT_SCOPE`, `SERVER_SCOPE`, or `SHARED_SCOPE`).
+
+> **Note:** Alarm rules do not support time series rolling arguments (`TS_ROLLING`). Calculated fields do; alarm rules do not.
+
+### Key
+
+`refEntityKey.key` identifies the exact data point the argument reads — a telemetry key or attribute name on the target entity.
+
+### Argument name
+
+The argument name is the key in the `arguments` map (e.g., `"temperature"`). It serves as the local variable name inside conditions, scripts, and `${argumentName}` placeholders in alarm details. It does not have to match the underlying `refEntityKey.key` — for example, an argument named `v_a` might read time series key `voltage_phase_a`.
+
+> **Note:** Do not name an argument `ctx` — in Script mode it shadows the TBEL `ctx` binding (`ctx.latestTs`, `ctx.args`) and breaks scripts that rely on it.
+
+### Default value
+
+`defaultValue` is substituted whenever the underlying key has no data at evaluation time. Always serialize it as a JSON string — even numeric or boolean fallbacks must be quoted (e.g., `"defaultValue": "0"`, not `"defaultValue": 0`). Omit unless the user explicitly asks for a fallback — silently substituting a value can mask missing-data problems or fire alarms the user didn't intend.
+
+## Trigger conditions
+
+A trigger condition tells the rule when to create or update an alarm at a given severity. Each entry in the `createRules` map is a trigger condition keyed by severity:
+
+```json
+"createRules": {
+  "<SEVERITY>": {
+    "condition": { "...": "see Condition below" },
+    "alarmDetails": "<optional text>",
+    "dashboardId": { "entityType": "DASHBOARD", "id": "<UUID>" }
+  }
+}
+```
+
+### Severity
+
+`<SEVERITY>` is the map key in `createRules` — one of `CRITICAL`, `MAJOR`, `MINOR`, `WARNING`, `INDETERMINATE`. It is not a property on the trigger object itself. A rule defines at most one trigger condition per severity and only needs to declare the severities it actually distinguishes.
+
+Trigger conditions are evaluated from highest to lowest severity — `CRITICAL` → `MAJOR` → `MINOR` → `WARNING` → `INDETERMINATE` — and the first matching condition determines the alarm's severity.
+
+Severity escalation behavior:
+
+- If no alarm of this type is active, a match creates a new alarm at the matched severity.
+- If an alarm is already active, a match at a **higher** severity raises the alarm's severity.
+- A match at the **same or lower** severity does not change the alarm; severity never decreases until the alarm clears.
+
+See SKILL.md for how severity behaves on the alarm record itself.
+
+### Condition
+
+The condition has two orthogonal parts:
+
+- **Mode** — how the logic is defined: *Simple* (filters) or *Script* (TBEL).
+- **Type** — when a match is recognized: *Simple* (immediate), *Duration* (sustained), or *Repeating* (consecutive).
+
+```json
+"condition": {
+  "type": "<SIMPLE | DURATION | REPEATING>",
+  "expression": { "...": "Simple- or Script-mode expression" },
+  "schedule": { "...": "see Schedule below" },
+  "unit": "<SECONDS | MINUTES | HOURS | DAYS>",
+  "value": { "staticValue": <integer> },
+  "count": { "staticValue": <integer> }
+}
+```
+
+The `type` field is the **condition type** (when to recognize a match). The **mode** is encoded inside `expression.type` (`SIMPLE` for filters, `TBEL` for script).
+
+Field presence:
+
+- `expression` is always required.
+- `unit` and `value` apply only when `condition.type` is `DURATION`.
+- `count` applies only when `condition.type` is `REPEATING`.
+- `schedule` is optional in all cases; `null` or absent means active all the time.
+
+`value` and `count` accept either `staticValue` (an integer) or `dynamicValueArgument` (the name of an argument that supplies the integer at runtime).
+
+#### Mode: Simple
+
+Simple mode combines argument filters with AND/OR:
+
+```json
+"expression": {
+  "type": "SIMPLE",
+  "operation": "<AND | OR>",
+  "filters": [
+    {
+      "argument": "<argName>",
+      "valueType": "<NUMERIC | STRING | BOOLEAN | DATE_TIME>",
+      "operation": "<AND | OR>",
+      "predicates": [ "..." ]
+    }
+  ]
+}
+```
+
+The expression-level `operation` combines argument filters. Each filter targets one argument; an argument can appear in at most one filter. Within a filter, predicates are combined with the filter's own `operation`.
+
+**Predicates** — each predicate is a single check on the filter's argument:
+
+```json
+{
+  "type": "<NUMERIC | STRING | BOOLEAN>",
+  "operation": "<operation>",
+  "value": { "staticValue": <value> }
+}
+```
+
+Supported operations per value type:
+
+- **Numeric** — `EQUAL`, `NOT_EQUAL`, `GREATER`, `LESS`, `GREATER_OR_EQUAL`, `LESS_OR_EQUAL`.
+- **String** — `EQUAL`, `NOT_EQUAL`, `STARTS_WITH`, `ENDS_WITH`, `CONTAINS`, `NOT_CONTAINS`, `IN`, `NOT_IN`. Optional `"ignoreCase": true`.
+- **Boolean** — `EQUAL`, `NOT_EQUAL`.
+- **Datetime** — predicate uses `"type": "NUMERIC"` with values as millisecond timestamps; the filter uses `"valueType": "DATE_TIME"`.
+
+For `IN` / `NOT_IN`, the value is a comma-separated string (e.g., `"error,warning,critical"`).
+
+To compare against another argument's current value, replace `staticValue` with `dynamicValueArgument`:
+
+```json
+{ "type": "NUMERIC", "operation": "GREATER", "value": { "dynamicValueArgument": "<argName>" } }
+```
+
+**Missing-for predicate** — triggers when no data has been received for a specified duration. Only available in Simple mode (TBEL cannot express this):
+
+```json
+{
+  "type": "NO_DATA",
+  "duration": { "staticValue": <integer> },
+  "unit": "<SECONDS | MINUTES | HOURS | DAYS>"
+}
+```
+
+**Complex predicate** — groups nested predicates with their own AND/OR combinator:
+
+```json
+{
+  "type": "COMPLEX",
+  "operation": "<AND | OR>",
+  "predicates": [ "..." ]
+}
+```
+
+Complex predicates can nest further, but readability drops fast past a single level — see Best practices.
+
+**Examples.**
+
+`temperature > 50 AND humidity > 80` — two filters joined by AND:
+
+```json
+{
+  "type": "SIMPLE",
+  "operation": "AND",
+  "filters": [
+    {
+      "argument": "temperature",
+      "valueType": "NUMERIC",
+      "operation": "AND",
+      "predicates": [{ "type": "NUMERIC", "operation": "GREATER", "value": { "staticValue": 50 } }]
+    },
+    {
+      "argument": "humidity",
+      "valueType": "NUMERIC",
+      "operation": "AND",
+      "predicates": [{ "type": "NUMERIC", "operation": "GREATER", "value": { "staticValue": 80 } }]
+    }
+  ]
+}
+```
+
+`temperature > 50 AND temperature < 100` — two predicates on one filter (an argument can appear in only one filter):
+
+```json
+{
+  "type": "SIMPLE",
+  "operation": "AND",
+  "filters": [
+    {
+      "argument": "temperature",
+      "valueType": "NUMERIC",
+      "operation": "AND",
+      "predicates": [
+        { "type": "NUMERIC", "operation": "GREATER", "value": { "staticValue": 50 } },
+        { "type": "NUMERIC", "operation": "LESS",    "value": { "staticValue": 100 } }
+      ]
+    }
+  ]
+}
+```
+
+#### Mode: Script (TBEL)
+
+Script mode uses a TBEL script for logic that filters cannot express — computations between arguments, multi-argument boolean logic, regex, substring extraction. The script must return a **boolean** (`true` or `false`).
+
+**Before writing any TBEL code, call `activate_skill` with `skill_name: "tbel"` unless `tbel` is already active in this conversation. This is mandatory.** TBEL is based on MVEL and adds security constraints and ThingsBoard-specific helpers — prior knowledge of MVEL or JavaScript is not sufficient and will lead to syntax errors and runtime failures. The alarm-rule-specific argument bindings and context object are documented below; the `tbel` skill covers the language itself.
+
+```json
+"expression": {
+  "type": "TBEL",
+  "expression": "<tbel script body>"
+}
+```
+
+Implicitly available inside the script:
+
+- **Argument variables** — each argument is exposed as a local variable named after its key in the `arguments` map. Value types: `boolean`, `long`, `double`, `string`, `JSON`.
+- `ctx.latestTs` — the latest timestamp (milliseconds) across all arguments.
+- `ctx.args` — a map of all arguments as objects with `ts` (milliseconds) and `value`. Use this when the script needs an argument's timestamp, not just its value.
+
+Example — trigger when temperature exceeds a dynamic threshold and humidity is below 20:
+
+```json
+"expression": {
+  "type": "TBEL",
+  "expression": "return temperature > threshold && humidity < 20;"
+}
+```
+
+#### When to use Simple vs Script
+
+- Use **Simple** for straightforward checks: single-argument thresholds, equality, ranges.
+- Use **Simple** when a `missing for` (no-data) predicate is needed — TBEL does not support it.
+- Use **Script** for calculations between arguments, multi-argument boolean logic, or advanced string operations (regex, substring extraction, concatenation).
+- Prefer **Script** over deeply nested complex predicates — TBEL is cleaner when mixing AND/OR across many checks.
+
+#### Condition type: Simple, Duration, Repeating
+
+- **Simple** — matches as soon as the logic evaluates to true. Set `condition.type` to `SIMPLE`. No additional fields.
+- **Duration** — matches only after the logic stays true continuously for a specified duration. Set `condition.type` to `DURATION` and add `unit` (`SECONDS`, `MINUTES`, `HOURS`, `DAYS`) plus `value` (the integer count). `value` can be `staticValue` or `dynamicValueArgument`.
+- **Repeating** — matches only after the logic evaluates to true a specified number of consecutive times. Set `condition.type` to `REPEATING` and add `count` (the integer). `count` can be `staticValue` or `dynamicValueArgument`.
+
+Use Duration or Repeating to dampen jittery signals — see Best practices.
+
+### Schedule
+
+The schedule restricts when the condition is evaluated. When an event's timestamp falls outside the allowed window, the condition is skipped entirely — the rule takes no action regardless of the data. Omit the field (`null` or absent) to evaluate at all times.
+
+> **Note:** Although Schedule and Condition appear as sibling fields in the UI, in JSON the schedule is nested inside the condition object.
+
+Conventions used by all schedule shapes:
+
+- Timezones are IANA identifiers (e.g., `Europe/Berlin`, `America/New_York`).
+- Days of the week are numbered 1 (Monday) through 7 (Sunday).
+- Time boundaries are milliseconds since midnight; `endsOn = 0` means end of day.
+
+**Active all the time** — explicit form of "no restriction":
+
+```json
+"schedule": { "staticValue": { "type": "ANY_TIME" } }
+```
+
+**Specific time** — a single time window applied on chosen days:
+
+```json
+"schedule": {
+  "staticValue": {
+    "type": "SPECIFIC_TIME",
+    "timezone": "America/New_York",
+    "daysOfWeek": [1, 2, 3, 4, 5],
+    "startsOn": 28800000,
+    "endsOn": 64800000
+  }
+}
+```
+
+**Custom** — per-day windows, with each day individually enabled:
+
+```json
+"schedule": {
+  "staticValue": {
+    "type": "CUSTOM",
+    "timezone": "America/New_York",
+    "items": [
+      { "dayOfWeek": 1, "enabled": true,  "startsOn": 32400000, "endsOn": 61200000 },
+      { "dayOfWeek": 2, "enabled": false },
+      { "dayOfWeek": 3, "enabled": true,  "startsOn": 0,        "endsOn": 0 }
+    ]
+  }
+}
+```
+
+**Dynamic** — the schedule object is resolved at runtime from an argument:
+
+```json
+"schedule": { "dynamicValueArgument": "<argName>" }
+```
+
+The referenced argument must supply a schedule object with the same shape as the `staticValue` content above.
+
+### Additional info
+
+`alarmDetails` is optional text shown in the alarm's details panel. Supports `${argumentName}` placeholders, replaced at runtime with the argument's current value:
+
+```
+"Temperature is ${temperature}, threshold is ${threshold}"
+```
+
+If `temperature` is 105 and `threshold` is 100, the rendered detail is: *"Temperature is 105, threshold is 100"*. The rendered string is written to the alarm's `details` JSON.
+
+### Mobile dashboard
+
+`dashboardId` is an optional reference to a dashboard. When set, that dashboard opens when a user taps the alarm in the ThingsBoard mobile app.
+
+## Clear condition
+
+The clear condition tells the rule when to automatically clear an active alarm. Optional — when omitted, alarms can only be cleared manually.
+
+```json
+"clearRule": {
+  "condition": { "...": "same shape as trigger condition" },
+  "alarmDetails": "<optional text>",
+  "dashboardId": { "entityType": "DASHBOARD", "id": "<UUID>" }
+}
+```
+
+A clear condition has the same fields as a trigger condition minus severity — see [Trigger conditions](#trigger-conditions) for the structure of `condition`, `alarmDetails`, and `dashboardId`.
+
+## Propagation
+
+Propagation controls where alarms created by this rule are visible beyond the originator. Without propagation, alarms are only visible on their originator.
+
+Flags live at the top level of `configuration`:
+
+| Flag                        | Effect                                                                                |
+|-----------------------------|---------------------------------------------------------------------------------------|
+| `propagate`                 | Visible on entities related to the originator (any relation type, unless restricted). |
+| `propagateRelationTypes`    | Optional list of relation types limiting `propagate`; empty list means all types.     |
+| `propagateToOwner`          | Visible on the originator's direct owner (customer or tenant).                        |
+| `propagateToOwnerHierarchy` | Visible up the entire owner chain.                                                    |
+| `propagateToTenant`         | Visible on the tenant entity.                                                         |
+
+All propagation flags default to `false`. They can be combined freely.
+
+Propagation does not duplicate alarms — each propagated view is the same record shown for a different entity. See SKILL.md for the alarm-side details.
+
+## Debug mode
+
+Debug mode records alarm-rule evaluation events for troubleshooting. Stored as `debugSettings` on the rule entity, alongside `configuration` (not inside it):
+
+```json
+"debugSettings": {
+  "failuresEnabled": true,
+  "allEnabled": false,
+  "allEnabledUntil": 1773049118758
+}
+```
+
+Two independent modes — either or both can be enabled:
+
+- **Failures only (24/7)** — `failuresEnabled: true`. Logs only evaluation failures; runs indefinitely.
+- **All messages** — `allEnabled: true` with `allEnabledUntil` set to the expiration timestamp (milliseconds since epoch). Logs every evaluation event; the platform disables this mode automatically once `allEnabledUntil` passes. Default duration is 15 minutes from enablement.
+
+## Tools
+
+Tools for managing alarm rules:
+
+- `find_alarm_rules` — search alarm rules by name or by host entity. Use to locate an existing rule before reading or modifying it.
+- `read_alarm_rule` — fetch an alarm rule's full JSON by UUID. Use before modifying a rule, and to inspect its current configuration.
+- `save_alarm_rule` — create or update an alarm rule. Pass the full rule JSON. If the JSON contains an `id`, the existing rule is updated; otherwise a new one is created.
+- `delete_alarm_rule` — delete an alarm rule by UUID.
+
+### Save JSON shape
+
+`save_alarm_rule` accepts the full alarm-rule JSON. The envelope:
+
+```json
+{
+  "id": { "entityType": "CALCULATED_FIELD", "id": "<UUID>" },
+  "name": "<alarm type>",
+  "entityId": { "entityType": "<DEVICE_PROFILE | ASSET_PROFILE | DEVICE | ASSET | CUSTOMER>", "id": "<UUID>" },
+  "configuration": { "type": "ALARM", "...": "see Configuration shape above" },
+  "debugSettings": { "...": "optional, omit unless requested" },
+  "additionalInfo": { "...": "optional" }
+}
+```
+
+Include `id` only when updating an existing rule (typically when the rule was loaded via `read_alarm_rule`). For creation, omit the field entirely — TB assigns the UUID.
+
+## Best practices
+
+### Locate before creating
+
+Before creating a new alarm rule, call `find_alarm_rules` on the host entity to discover existing rules. If a rule with the same alarm type already exists on the host, extend it (additional severities, refined conditions) rather than creating a parallel rule — only one active alarm per type can exist per originator, so two rules with the same alarm type compete for the same alarm slot.
+
+### Inspect alarms before designing rules
+
+When the user's request relates to existing alarm patterns or noisy alarms, call `find_alarms` first to see what's actually firing. Real alarm data — severity distribution, frequency, originator spread — informs better rule changes than the user's description alone.
+
+### Preserve existing properties when modifying
+
+When modifying an existing alarm rule (loaded via `read_alarm_rule`), preserve the rule's `id`, `name`, `entityId`, and `debugSettings` verbatim unless the user explicitly asks to change them. The alarm type (stored as `name`) and the severity-to-condition mapping carry operational history that downstream consumers depend on — alarms already in flight tie back to those identifiers. Add or change only what the request requires.
+
+### Match configuration to real data
+
+Thresholds, value types, and condition logic should match the data as it exists on the entity, not the wording of the request. A user asking to "alert on high temperature" may be reading a key called `t`, in Fahrenheit, with typical values around 70 — the rule should reflect that reality (the real key, the real scale) rather than mirror the phrasing. When entity data is available, inspect it before picking thresholds and value types.
+
+### Use descriptive argument names
+
+Argument names appear directly in conditions, scripts, and `${argumentName}` placeholders, so they should make the rule read on its own. Choose names that describe what the value represents — typically the source key name, or a name reflecting the value's role. Avoid generic placeholders like `x`, `y`, `arg1`, `value`. Match the casing style of the source keys (`snake_case` vs `camelCase`); default to `camelCase` when unclear.
+
+### Don't add default values proactively
+
+Setting a `defaultValue` on an argument silently changes rule behavior when inputs are missing — it can fire alarms the user didn't intend or suppress ones they did. Add one only when the user explicitly asks for a fallback, or the request makes the intent unambiguous. When in doubt, omit it.
+
+### Group related incidents under one alarm type
+
+An alarm rule has one alarm type, shared by every trigger condition inside it. Severity escalation works only within a single type — a `WARNING` alarm can escalate to `CRITICAL` within the same rule, but two separate rules with types *"High Temp Warning"* and *"High Temp Critical"* produce two unrelated alarms instead. Pick an alarm type that names the *kind* of problem (*High Temperature*, *Low Battery*), and keep severity and thresholds out of the name.
+
+### Define only the severities you need
+
+Trigger conditions are optional per severity — define only the ones the use case actually distinguishes. A rule with one `CRITICAL` trigger is often clearer than a rule with four near-duplicate triggers at `MINOR` / `MAJOR` / `CRITICAL` / `INDETERMINATE` that differ only by threshold. Add a severity when the threshold and the operational response meaningfully differ, not because the enum offers it.
+
+### Dampen noisy signals
+
+For telemetry that jitters around a threshold, use the **Duration** or **Repeating** condition type instead of **Simple**. A Simple condition on a flapping signal raises an alarm on every crossing, even for a single noisy reading. Duration ("high for 5 minutes") or Repeating ("high 3 readings in a row") fires only after the signal is consistently out of range.
+
+### Keep complex predicates shallow
+
+A complex predicate can nest further complex predicates, but readability drops fast past a single level — a tree of AND/OR groupings is hard to follow and harder to maintain. Stick to one level of nesting: a single complex predicate grouping plain predicates with AND/OR is fine, anything deeper is a signal that the logic belongs in Script mode, where TBEL expresses nested boolean logic more clearly.
+
+### Leave a gap between trigger and clear thresholds
+
+When a trigger condition and a clear condition check the same argument, their thresholds should not meet. A rule that triggers on `value > 50` and clears on `value <= 50` flaps every time the value oscillates across the boundary. A gap — trigger on `> 50`, clear on `< 45` — keeps the alarm stable once raised.
+
+### Keep propagation off by default
+
+Leave propagation flags off unless there is a concrete reason to turn them on. Propagation makes alarms visible on owners, tenants, or related entities, which clutters dashboards for users who don't need to see them. Turn propagation on only when someone specifically needs to monitor the alarm outside its originator — for example, a tenant-level operator watching for critical events across all devices.
+
+## Examples
+
+### Creating an alarm rule
+
+**User request**
+
+> On the Tank device profile, raise a CRITICAL alarm called "Sudden Fuel Drop" when `fuelLevelDrop` exceeds 5, and clear it once `fuelLevelDrop` is back to 1 or below. Include the latest drop in the alarm details.
+
+**Expected alarm rule JSON**
+
+```json
+{
+  "name": "Sudden Fuel Drop",
+  "entityId": {
+    "entityType": "DEVICE_PROFILE",
+    "id": "<tank profile UUID>"
+  },
+  "configuration": {
+    "type": "ALARM",
+    "arguments": {
+      "fuelLevelDrop": {
+        "refEntityKey": { "key": "fuelLevelDrop", "type": "TS_LATEST" }
+      }
+    },
+    "createRules": {
+      "CRITICAL": {
+        "condition": {
+          "type": "SIMPLE",
+          "expression": {
+            "type": "SIMPLE",
+            "operation": "AND",
+            "filters": [
+              {
+                "argument": "fuelLevelDrop",
+                "valueType": "NUMERIC",
+                "operation": "AND",
+                "predicates": [
+                  { "type": "NUMERIC", "operation": "GREATER", "value": { "staticValue": 5.0 } }
+                ]
+              }
+            ]
+          },
+          "schedule": null
+        },
+        "alarmDetails": "Sudden fuel drop detected: ${fuelLevelDrop}"
+      }
+    },
+    "clearRule": {
+      "condition": {
+        "type": "SIMPLE",
+        "expression": {
+          "type": "SIMPLE",
+          "operation": "AND",
+          "filters": [
+            {
+              "argument": "fuelLevelDrop",
+              "valueType": "NUMERIC",
+              "operation": "AND",
+              "predicates": [
+                { "type": "NUMERIC", "operation": "LESS_OR_EQUAL", "value": { "staticValue": 1.0 } }
+              ]
+            }
+          ]
+        },
+        "schedule": null
+      },
+      "alarmDetails": "Fuel level stabilized: ${fuelLevelDrop}"
+    },
+    "propagate": false,
+    "propagateToOwner": false,
+    "propagateToOwnerHierarchy": false,
+    "propagateToTenant": false,
+    "propagateRelationTypes": []
+  }
+}
+```
+
+Highlights:
+- The rule's `name` (`"Sudden Fuel Drop"`) becomes the `type` field on every alarm it creates.
+- Profile host (`DEVICE_PROFILE`) — the rule applies to every tank using this profile, with each tank as the originator of its own alarm.
+- Single argument from the current entity — `refEntityId` and `refDynamicSourceConfiguration` are omitted.
+- Simple mode (`expression.type: "SIMPLE"`) with one filter and one predicate — the most common shape.
+- Simple condition type (`condition.type: "SIMPLE"`) — no Duration or Repeating dampening because the request didn't ask for it. See Best practices for when to add dampening.
+- Trigger and clear thresholds leave a gap (`> 5` vs `<= 1`) so the alarm doesn't flap.
+- `alarmDetails` uses a `${fuelLevelDrop}` placeholder that resolves at trigger time.
+- Propagation flags are all `false` — no relation visibility was requested.
+- `debugSettings` omitted because the user did not ask for it.
+
+### Modifying an alarm rule
+
+**Existing alarm rule** (loaded via `read_alarm_rule`)
+
+```json
+{
+  "id": { "entityType": "CALCULATED_FIELD", "id": "1f4c8e2a-9b3d-4e5f-8a1b-c2d3e4f5a6b7" },
+  "name": "Sudden Fuel Drop",
+  "entityId": {
+    "entityType": "DEVICE_PROFILE",
+    "id": "<tank profile UUID>"
+  },
+  "configuration": {
+    "type": "ALARM",
+    "arguments": {
+      "fuelLevelDrop": {
+        "refEntityKey": { "key": "fuelLevelDrop", "type": "TS_LATEST" }
+      }
+    },
+    "createRules": {
+      "CRITICAL": {
+        "condition": {
+          "type": "SIMPLE",
+          "expression": {
+            "type": "SIMPLE",
+            "operation": "AND",
+            "filters": [
+              {
+                "argument": "fuelLevelDrop",
+                "valueType": "NUMERIC",
+                "operation": "AND",
+                "predicates": [
+                  { "type": "NUMERIC", "operation": "GREATER", "value": { "staticValue": 5.0 } }
+                ]
+              }
+            ]
+          },
+          "schedule": null
+        },
+        "alarmDetails": "Sudden fuel drop detected: ${fuelLevelDrop}"
+      }
+    },
+    "clearRule": {
+      "condition": {
+        "type": "SIMPLE",
+        "expression": {
+          "type": "SIMPLE",
+          "operation": "AND",
+          "filters": [
+            {
+              "argument": "fuelLevelDrop",
+              "valueType": "NUMERIC",
+              "operation": "AND",
+              "predicates": [
+                { "type": "NUMERIC", "operation": "LESS_OR_EQUAL", "value": { "staticValue": 1.0 } }
+              ]
+            }
+          ]
+        },
+        "schedule": null
+      },
+      "alarmDetails": "Fuel level stabilized: ${fuelLevelDrop}"
+    },
+    "propagate": false,
+    "propagateToOwner": false,
+    "propagateToOwnerHierarchy": false,
+    "propagateToTenant": false,
+    "propagateRelationTypes": []
+  }
+}
+```
+
+**User request**
+
+> Also raise a MAJOR alarm when the drop is between 2 and 5 — but only if it stays that way for 5 minutes, so quick dips don't trigger.
+
+**Expected alarm rule JSON**
+
+```json
+{
+  "id": { "entityType": "CALCULATED_FIELD", "id": "1f4c8e2a-9b3d-4e5f-8a1b-c2d3e4f5a6b7" },
+  "name": "Sudden Fuel Drop",
+  "entityId": {
+    "entityType": "DEVICE_PROFILE",
+    "id": "<tank profile UUID>"
+  },
+  "configuration": {
+    "type": "ALARM",
+    "arguments": {
+      "fuelLevelDrop": {
+        "refEntityKey": { "key": "fuelLevelDrop", "type": "TS_LATEST" }
+      }
+    },
+    "createRules": {
+      "CRITICAL": {
+        "condition": {
+          "type": "SIMPLE",
+          "expression": {
+            "type": "SIMPLE",
+            "operation": "AND",
+            "filters": [
+              {
+                "argument": "fuelLevelDrop",
+                "valueType": "NUMERIC",
+                "operation": "AND",
+                "predicates": [
+                  { "type": "NUMERIC", "operation": "GREATER", "value": { "staticValue": 5.0 } }
+                ]
+              }
+            ]
+          },
+          "schedule": null
+        },
+        "alarmDetails": "Sudden fuel drop detected: ${fuelLevelDrop}"
+      },
+      "MAJOR": {
+        "condition": {
+          "type": "DURATION",
+          "unit": "MINUTES",
+          "value": { "staticValue": 5 },
+          "expression": {
+            "type": "SIMPLE",
+            "operation": "AND",
+            "filters": [
+              {
+                "argument": "fuelLevelDrop",
+                "valueType": "NUMERIC",
+                "operation": "AND",
+                "predicates": [
+                  { "type": "NUMERIC", "operation": "GREATER",          "value": { "staticValue": 2.0 } },
+                  { "type": "NUMERIC", "operation": "LESS_OR_EQUAL",    "value": { "staticValue": 5.0 } }
+                ]
+              }
+            ]
+          },
+          "schedule": null
+        },
+        "alarmDetails": "Sustained fuel drop: ${fuelLevelDrop}"
+      }
+    },
+    "clearRule": {
+      "condition": {
+        "type": "SIMPLE",
+        "expression": {
+          "type": "SIMPLE",
+          "operation": "AND",
+          "filters": [
+            {
+              "argument": "fuelLevelDrop",
+              "valueType": "NUMERIC",
+              "operation": "AND",
+              "predicates": [
+                { "type": "NUMERIC", "operation": "LESS_OR_EQUAL", "value": { "staticValue": 1.0 } }
+              ]
+            }
+          ]
+        },
+        "schedule": null
+      },
+      "alarmDetails": "Fuel level stabilized: ${fuelLevelDrop}"
+    },
+    "propagate": false,
+    "propagateToOwner": false,
+    "propagateToOwnerHierarchy": false,
+    "propagateToTenant": false,
+    "propagateRelationTypes": []
+  }
+}
+```
+
+Highlights:
+- The new `MAJOR` trigger was added alongside the existing `CRITICAL` trigger — same alarm type, so a `MAJOR` alarm escalates to `CRITICAL` when the drop crosses 5, instead of producing two unrelated alarms.
+- Two predicates on a single filter encode the `2 < fuelLevelDrop <= 5` range — an argument can appear in only one filter per expression, so both checks live in the same filter combined with `AND`.
+- Duration condition type (`condition.type: "DURATION"`, `unit: "MINUTES"`, `value.staticValue: 5`) implements the "stays that way for 5 minutes" requirement — dampens transient dips without changing the existing CRITICAL behavior.
+- The clear condition is unchanged. The existing trigger and clear thresholds (`> 5` and `<= 1`) already leave a gap; the new MAJOR threshold (`> 2`) also sits above the clear threshold, so the alarm clears cleanly once the drop returns below 1.
+- `id` is preserved verbatim from the loaded rule — required so `save_alarm_rule` updates instead of creating.
+- `name`, `entityId`, propagation flags, and the existing `CRITICAL` trigger are copied verbatim.