docs(client): document Galaxy fallback operator-comment limitation + pin null behavior

Closes backlog #12: Galaxy's AckMsg attribute is WRITE-ONLY and the OPC UA
event SelectClause carries no comment field, making OperatorComment
unrecoverable on the sub-attribute fallback path. Documents the two concrete
reasons in-code and tightens the AlarmEventArgs XML doc; adds pinning test
OnAlarmEvent_GalaxyFallback_LeavesOperatorCommentNull.

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Models/AlarmEventArgs.cs

@@ -81,9 +81,13 @@ public sealed class AlarmEventArgs : EventArgs
 
     /// <summary>
     ///     PR E.7 — Operator-supplied comment recorded by the upstream alarm system on
-    ///     Acknowledge transitions. Null on raise / clear, or when the upstream path
-    ///     can't surface the comment (sub-attribute fallback path collapses comments
-    ///     into a single string write).
+    ///     Acknowledge transitions. Null on raise / clear events, and intentionally null
+    ///     on the Galaxy OPC UA sub-attribute fallback path for two unrecoverable reasons:
+    ///     (a) Galaxy's <c>AckMsg</c> attribute is WRITE-ONLY — no readable attribute
+    ///     exposes the last operator comment — and (b) the OPC UA event SelectClause
+    ///     carries no comment field. The operator comment is only available via the
+    ///     gateway's native alarm feed (<c>GalaxyAlarmTransition.OperatorComment</c>
+    ///     in the Galaxy driver path).
     /// </summary>
     public string? OperatorComment { get; }
 

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/OpcUaClientService.cs

@@ -814,6 +814,15 @@ public sealed class OpcUaClientService : IOpcUaClientService
                     // Other supplemental read failure; deliver event with defaults
                 }
 
+                // OperatorComment is intentionally left null (default) here.
+                // Two concrete reasons make it unrecoverable in this Galaxy sub-attribute fallback path:
+                //   (a) Galaxy's AckMsg attribute is WRITE-ONLY — there is no readable attribute that
+                //       exposes the last operator comment, so no supplemental read can recover it.
+                //   (b) The OPC UA event SelectClause (CreateAlarmEventFilter) carries no comment field;
+                //       the OPC UA event notification itself never delivers a comment string.
+                // The operator comment is only available via the gateway's native alarm feed
+                // (the Galaxy driver path, GalaxyAlarmTransition.OperatorComment), not this
+                // OpcUaClient sub-attribute fallback.
                 AlarmEvent?.Invoke(this, new AlarmEventArgs(
                     sourceName, conditionName, severity, capturedMessage, retain, activeState, ackedState, time,
                     eventId, capturedConditionNodeId));