diff --git a/docs/ScriptedAlarms.md b/docs/ScriptedAlarms.md
index c3a7cbf8..00c18794 100644
--- a/docs/ScriptedAlarms.md
+++ b/docs/ScriptedAlarms.md
@@ -142,6 +142,35 @@ ObjectType. `severity` seeds the condition's initial severity at materialisation
 the driver's live alarm events may carry a different severity that overrides it at
 runtime.
 
+#### Severity mapping
+
+The authored `severity` (1–1000) seeds the OPC UA condition node at materialisation
+time. On the **first native transition** the value snaps to one of four fixed buckets
+via `NativeAlarmProjector.MapSeverity`:
+
+| `AlarmSeverity` enum | Projected value |
+|---|---|
+| `Low` | 200 |
+| `Medium` | 500 |
+| `High` | 700 |
+| `Critical` | 900 |
+| *(default/unspecified)* | 500 |
+
+That projected integer is then mapped to the OPC UA SDK `EventSeverity` enum
+by `OtOpcUaNodeManager.MapSeverity` on each `AlarmStateUpdate` write:
+
+| Projected value range | `EventSeverity` |
+|---|---|
+| < 200 | `Low` |
+| 200 – 399 | `MediumLow` |
+| 400 – 599 | `Medium` |
+| 600 – 799 | `MediumHigh` |
+| ≥ 800 | `High` |
+
+Consequently the four authored buckets land as: Low→`MediumLow`, Medium→`Medium`,
+High→`MediumHigh`, Critical→`High`. The authored `severity` field has no effect after
+the first transition.
+
 ### Runtime flow
 
 The driver's live `IAlarmSource.OnAlarmEvent` is the sole input. Transition kinds