docs(alarms): document alarmmgr->subtag fallback (providers, failover, config, contract, parity)

docs/GatewayConfiguration.md

@@ -230,6 +230,74 @@ behavior.
 The alarm monitor is independent of client sessions: `AcknowledgeAlarm` and
 `StreamAlarms` are session-less RPCs served by the monitor.
 
+### Alarm fallback options
+
+The `Fallback` sub-section controls how the alarm feed selects between the
+native wnwrap alarm-manager provider and the subtag-monitoring fallback.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `MxGateway:Alarms:Fallback:Mode` | `Auto` | Provider selection mode. `Auto` uses the alarm manager as primary and fails over to subtag monitoring after consecutive COM failures, then fails back automatically. `ForceAlarmManager` disables failover. `ForceSubtag` forces subtag monitoring on from startup. Values are case-insensitive. |
+| `MxGateway:Alarms:Fallback:ConsecutiveFailureThreshold` | `3` | Number of consecutive wnwrap COM failures (`COMException` or failure HRESULT from `Subscribe` / `GetXmlCurrentAlarms2`) before the monitor switches to subtag mode. Floored at 1. |
+| `MxGateway:Alarms:Fallback:FailbackProbeIntervalSeconds` | `30` | While in subtag mode, how often (in seconds) the monitor probes the wnwrap provider to detect recovery. Floored at 1. |
+| `MxGateway:Alarms:Fallback:FailbackStableProbes` | `3` | Number of consecutive clean wnwrap probes required before the monitor switches back to the alarm manager. Floored at 1. |
+| `MxGateway:Alarms:Fallback:Discovery:UseGalaxyRepository` | `true` | When `true`, the monitor queries the Galaxy Repository SQL database to build the subtag watch-list for the configured area. |
+| `MxGateway:Alarms:Fallback:Discovery:Area` | _(empty)_ | Galaxy area to scope the Repository query to. Falls back to `MxGateway:Alarms:DefaultArea` when empty. Ignored when `UseGalaxyRepository` is `false`. |
+| `MxGateway:Alarms:Fallback:Discovery:IncludeAttributes` | _(empty)_ | Explicit MXAccess attribute paths to add to the subtag watch-list, supplementing (or replacing, when `UseGalaxyRepository` is `false`) the Repository-derived list. |
+| `MxGateway:Alarms:Fallback:Discovery:ExcludeAttributes` | _(empty)_ | Attribute paths to remove from the Repository-derived watch-list. Ignored when `UseGalaxyRepository` is `false`. |
+| `MxGateway:Alarms:Fallback:Subtags:Active` | `active` | Subtag name for the in-alarm boolean. |
+| `MxGateway:Alarms:Fallback:Subtags:Acked` | `acked` | Subtag name for the acknowledged boolean. |
+| `MxGateway:Alarms:Fallback:Subtags:AckComment` | _(empty)_ | Subtag name for the acknowledgement comment attribute. When empty, writing an ack comment in subtag mode is disabled. Must be verified against the live MXAccess attribute set before use. |
+| `MxGateway:Alarms:Fallback:Subtags:Priority` | `priority` | Subtag name for the alarm priority / severity value. |
+
+Validation rules:
+
+- `Mode` must be `Auto`, `ForceAlarmManager`, or `ForceSubtag` (case-insensitive).
+- `Mode = ForceSubtag` with both `UseGalaxyRepository = false` and an empty
+  `IncludeAttributes` list produces a startup validation warning: the subtag
+  provider has no attributes to advise.
+- `ConsecutiveFailureThreshold`, `FailbackProbeIntervalSeconds`, and
+  `FailbackStableProbes` are floored at 1 by `GatewayOptionsValidator`.
+
+Full example with non-default fallback settings:
+
+```json
+{
+  "MxGateway": {
+    "Alarms": {
+      "Enabled": true,
+      "SubscriptionExpression": "\\\\SCADA01\\Galaxy!PlantArea",
+      "DefaultArea": "PlantArea",
+      "ReconcileIntervalSeconds": 30,
+      "Fallback": {
+        "Mode": "Auto",
+        "ConsecutiveFailureThreshold": 3,
+        "FailbackProbeIntervalSeconds": 30,
+        "FailbackStableProbes": 3,
+        "Discovery": {
+          "UseGalaxyRepository": true,
+          "Area": "",
+          "IncludeAttributes": [],
+          "ExcludeAttributes": []
+        },
+        "Subtags": {
+          "Active": "active",
+          "Acked": "acked",
+          "AckComment": "",
+          "Priority": "priority"
+        }
+      }
+    }
+  }
+}
+```
+
+The exact AVEVA subtag names for `Active`, `Acked`, `AckComment`, and
+`Priority` are not hard-coded. The `Subtags` block exists so names can be
+confirmed against the live MXAccess attribute set and configured without a
+code change. See `docs/AlarmClientDiscovery.md` for the synthesis rules that
+depend on these names.
+
 ## Host Endpoints and Transport Security (Kestrel)
 
 The listening endpoints are **not** part of the `MxGateway` section. The gateway