docs(src): add missing XML docs and strip tracking-ID comments

Sweep of 203 source files resolving CommentChecker findings: add
<summary>/<param>/<returns>/<inheritdoc> where missing, and remove
resolved task/issue tracking markers (Tests-NNN, Worker-NNN, Server-NNN,
Task N) from code comments. Comment/doc-only — no logic changes.
Server+Tests build clean under TreatWarningsAsErrors.

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/DashboardPageBase.cs

@@ -38,7 +38,8 @@ public abstract class DashboardPageBase : ComponentBase, IAsyncDisposable
         await ConnectHubAsync().ConfigureAwait(false);
     }
 
-    /// <inheritdoc />
+    /// <summary>Disposes the SignalR hub connection created for this page, tolerating disposal-time errors.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async ValueTask DisposeAsync()
     {
         if (_hub is not null)

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardApiKeyAuthorization.cs

@@ -6,6 +6,7 @@ public sealed class DashboardApiKeyAuthorization
 {
     /// <summary>Determines whether the user can manage API keys.</summary>
     /// <param name="user">The authenticated user principal.</param>
+    /// <returns><see langword="true"/> if the user is authenticated and holds the <see cref="DashboardRoles.Admin"/> role; otherwise <see langword="false"/>.</returns>
     public bool CanManage(ClaimsPrincipal user)
     {
         if (user.Identity?.IsAuthenticated != true)

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardApiKeyManagementService.cs

@@ -20,17 +20,13 @@ public sealed class DashboardApiKeyManagementService(
     private const string UnauthorizedMessage = "Sign in with an authorized LDAP account to manage API keys.";
     private const string PepperUnavailableMarker = "pepper unavailable";
 
-    /// <summary>Determines whether the user can manage API keys.</summary>
-    /// <param name="user">The authenticated user principal.</param>
+    /// <inheritdoc />
     public bool CanManage(ClaimsPrincipal user)
     {
         return authorization.CanManage(user);
     }
 
-    /// <summary>Creates an API key asynchronously.</summary>
-    /// <param name="user">The authenticated user principal.</param>
-    /// <param name="request">The request payload.</param>
-    /// <param name="cancellationToken">Token to observe for cancellation.</param>
+    /// <inheritdoc />
     public async Task<DashboardApiKeyManagementResult> CreateAsync(
         ClaimsPrincipal user,
         DashboardApiKeyManagementRequest request,
@@ -82,10 +78,7 @@ public sealed class DashboardApiKeyManagementService(
         }
     }
 
-    /// <summary>Revokes an API key asynchronously.</summary>
-    /// <param name="user">The authenticated user principal.</param>
-    /// <param name="keyId">The API key identifier.</param>
-    /// <param name="cancellationToken">Token to observe for cancellation.</param>
+    /// <inheritdoc />
     public async Task<DashboardApiKeyManagementResult> RevokeAsync(
         ClaimsPrincipal user,
         string keyId,
@@ -120,10 +113,7 @@ public sealed class DashboardApiKeyManagementService(
             : DashboardApiKeyManagementResult.Fail("API key was not found or is already revoked.");
     }
 
-    /// <summary>Rotates an API key secret asynchronously.</summary>
-    /// <param name="user">The authenticated user principal.</param>
-    /// <param name="keyId">The API key identifier.</param>
-    /// <param name="cancellationToken">Token to observe for cancellation.</param>
+    /// <inheritdoc />
     public async Task<DashboardApiKeyManagementResult> RotateAsync(
         ClaimsPrincipal user,
         string keyId,
@@ -170,10 +160,7 @@ public sealed class DashboardApiKeyManagementService(
         }
     }
 
-    /// <summary>Deletes a revoked API key asynchronously.</summary>
-    /// <param name="user">The authenticated user principal.</param>
-    /// <param name="keyId">The API key identifier.</param>
-    /// <param name="cancellationToken">Token to observe for cancellation.</param>
+    /// <inheritdoc />
     public async Task<DashboardApiKeyManagementResult> DeleteAsync(
         ClaimsPrincipal user,
         string keyId,
@@ -242,15 +229,15 @@ public sealed class DashboardApiKeyManagementService(
 
     /// <summary>
     /// Emits the dashboard's own canonical <see cref="AuditEvent"/> for a <c>dashboard-*</c> op
-    /// directly through the best-effort <see cref="IAuditWriter"/> (Task 2.3 #6). This is in
+    /// directly through the best-effort <see cref="IAuditWriter"/>. This is in
     /// addition to the <c>create/revoke/rotate-key</c> event that <see cref="ApiKeyAdminCommands"/>
     /// emits via the canonical-forwarding <c>IApiKeyAuditStore</c> adapter — the doubled-audit
     /// behaviour is preserved, both rows now land in the canonical <c>audit_event</c> store.
     /// </summary>
     /// <remarks>
-    /// Phase 3 (Actor = operator principal): <c>Actor</c> is the LDAP operator who performed the
+    /// <c>Actor</c> is the LDAP operator who performed the
     /// action (resolved from the <paramref name="user"/> principal); <c>Target</c> is the managed
-    /// API key id. This fixes the pre-Phase-3 semantic gap where both fields held the keyId.
+    /// API key id. This fixes an earlier semantic gap where both fields held the keyId.
     /// </remarks>
     private async Task WriteDashboardAuditAsync(
         ClaimsPrincipal user,

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardAuthenticationResult.cs

@@ -23,6 +23,7 @@ public sealed record DashboardAuthenticationResult(
     /// Creates a successful authentication result.
     /// </summary>
     /// <param name="principal">Authenticated principal.</param>
+    /// <returns>A successful <see cref="DashboardAuthenticationResult"/> wrapping <paramref name="principal"/>.</returns>
     public static DashboardAuthenticationResult Success(ClaimsPrincipal principal)
     {
         return new DashboardAuthenticationResult(true, principal, null);
@@ -32,6 +33,7 @@ public sealed record DashboardAuthenticationResult(
     /// Creates a failed authentication result.
     /// </summary>
     /// <param name="failureMessage">Diagnostic message describing the failure.</param>
+    /// <returns>A failed <see cref="DashboardAuthenticationResult"/> carrying <paramref name="failureMessage"/>.</returns>
     public static DashboardAuthenticationResult Fail(string failureMessage)
     {
         return new DashboardAuthenticationResult(false, null, failureMessage);

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardAuthenticator.cs

@@ -16,7 +16,7 @@ namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
 /// shaped exactly as before (see <see cref="CreatePrincipal"/>).
 /// </summary>
 /// <param name="ldapAuthService">Shared LDAP bind-then-search provider.</param>
-/// <param name="roleMapper">Maps LDAP groups to dashboard roles (Task 1.1 seam).</param>
+/// <param name="roleMapper">Maps LDAP groups to dashboard roles.</param>
 /// <param name="logger">Logger for diagnostic, credential-free login outcomes.</param>
 public sealed class DashboardAuthenticator(
     ILdapAuthService ldapAuthService,
@@ -107,11 +107,11 @@ public sealed class DashboardAuthenticator(
         [
             // Keep NameIdentifier so any existing read-site that uses it continues to work.
             new Claim(ClaimTypes.NameIdentifier, username),
-            // Canonical login-username claim (Task 1.5).
+            // Canonical login-username claim.
             new Claim(ZbClaimTypes.Username, username),
             // ZbClaimTypes.Name == ClaimTypes.Name — drives Identity.Name resolution.
             new Claim(ZbClaimTypes.Name, displayName),
-            // Canonical display-name claim for cross-app consistency (Task 1.5).
+            // Canonical display-name claim for cross-app consistency.
             new Claim(ZbClaimTypes.DisplayName, displayName),
         ];
 

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardConnectionStringDisplay.cs

@@ -6,6 +6,7 @@ public static class DashboardConnectionStringDisplay
 {
     /// <summary>Returns a sanitized Galaxy Repository connection string for display.</summary>
     /// <param name="connectionString">The connection string to sanitize.</param>
+    /// <returns>A connection string with only display-safe fields, or a placeholder if it cannot be parsed.</returns>
     public static string GalaxyRepositoryConnectionString(string connectionString)
     {
         try

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardGroupRoleMapper.cs

@@ -17,7 +17,10 @@ namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
 public sealed class DashboardGroupRoleMapper(IOptions<GatewayOptions> options)
     : IGroupRoleMapper<string>
 {
-    /// <inheritdoc />
+    /// <summary>Maps the supplied dashboard LDAP group memberships to a dashboard role.</summary>
+    /// <param name="groups">The user's directory group memberships.</param>
+    /// <param name="ct">A token to request cancellation of the operation.</param>
+    /// <returns>The dashboard roles granted; scope is unused and always <see langword="null"/>.</returns>
     public Task<GroupRoleMapping<string>> MapAsync(
         IReadOnlyList<string> groups,
         CancellationToken ct)

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardGroupRoleMapping.cs

@@ -16,6 +16,7 @@ internal static class DashboardGroupRoleMapping
     /// </summary>
     /// <param name="groups">The collection of LDAP groups the user belongs to.</param>
     /// <param name="groupToRole">The mapping from group names to dashboard role names.</param>
+    /// <returns>The distinct dashboard roles the groups map to, or an empty list if none match.</returns>
     internal static IReadOnlyList<string> MapGroupsToRoles(
         IEnumerable<string> groups,
         IReadOnlyDictionary<string, string> groupToRole)
@@ -30,25 +31,6 @@ internal static class DashboardGroupRoleMapping
         {
             string normalizedGroup = group.Trim();
 
-            // Lookup precedence (Server-040): the full literal group string is
-            // tried first; only if that misses do we fall back to the leading
-            // RDN value (e.g. "GwAdmin" extracted from
-            // "ou=GwAdmin,ou=groups,..."). The map's comparer is
-            // OrdinalIgnoreCase (see DashboardOptions.GroupToRole), so e.g.
-            // "GwAdmin" and "gwadmin" both match.
-            //
-            // Review C1: with the shared ZB.MOM.WW.Auth.Ldap provider, groups
-            // arrive here already stripped to short RDN names (the library calls
-            // FirstRdnValue before returning them). So through the live login path
-            // the full-string branch only ever sees short names and the RDN
-            // fallback is effectively a no-op — they collapse to the same key.
-            // The fallback is retained because this mapping is also reachable
-            // directly via the IGroupRoleMapper<string> seam (DashboardGroupRoleMapper),
-            // where a caller could still pass a full DN. CONSEQUENCE: configuring a
-            // full-DN GroupToRole *key* (e.g. "ou=GwAdmin,ou=groups,...") is
-            // UNSUPPORTED with the shared library — the incoming group is a short
-            // name, so it will never equal a full-DN key. Keep GroupToRole keys as
-            // short group names.
             if (groupToRole.TryGetValue(normalizedGroup, out string? mapped)
                 || groupToRole.TryGetValue(ExtractFirstRdnValue(normalizedGroup), out mapped))
             {
@@ -61,6 +43,7 @@ internal static class DashboardGroupRoleMapping
 
     /// <summary>Extracts the first RDN value from a distinguished name.</summary>
     /// <param name="distinguishedName">The LDAP distinguished name.</param>
+    /// <returns>The value of the first RDN component, or the input unchanged if it contains no '=' separator.</returns>
     internal static string ExtractFirstRdnValue(string distinguishedName)
     {
         int equalsIndex = distinguishedName.IndexOf('=');

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardLiveDataService.cs

@@ -193,7 +193,8 @@ public sealed class DashboardLiveDataService : IDashboardLiveDataService, IAsync
         }
     }
 
-    /// <inheritdoc />
+    /// <summary>Closes the underlying gateway session, if one is open.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async ValueTask DisposeAsync()
     {
         if (_disposed)

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardRoles.cs

@@ -8,7 +8,7 @@ public static class DashboardRoles
 {
     /// <summary>
     /// Read-write access: API-key CRUD, settings, any state-changing UI.
-    /// Canonical role value (Task 1.7); formerly <c>"Admin"</c> — pure value
+    /// Canonical role value; formerly <c>"Admin"</c> — pure value
     /// rename, the operations this role authorizes are unchanged.
     /// </summary>
     public const string Admin = "Administrator";

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardServiceCollectionExtensions.cs

@@ -25,6 +25,7 @@ public static class DashboardServiceCollectionExtensions
     /// from the <c>MxGateway:Ldap</c> section. Also read to select the dashboard
     /// authentication scheme via the <c>MxGateway:Dashboard:DisableLogin</c> dev flag.
     /// </param>
+    /// <returns>The service collection, for chaining.</returns>
     public static IServiceCollection AddGatewayDashboard(
         this IServiceCollection services,
         IConfiguration configuration)

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSessionAdminResult.cs

@@ -6,6 +6,7 @@ public sealed record DashboardSessionAdminResult(
 {
     /// <summary>Creates a successful result with the given message.</summary>
     /// <param name="message">The result message.</param>
+    /// <returns>A successful <see cref="DashboardSessionAdminResult"/>.</returns>
     public static DashboardSessionAdminResult Success(string message)
     {
         return new DashboardSessionAdminResult(true, message);
@@ -13,6 +14,7 @@ public sealed record DashboardSessionAdminResult(
 
     /// <summary>Creates a failed result with the given message.</summary>
     /// <param name="message">The result message.</param>
+    /// <returns>A failed <see cref="DashboardSessionAdminResult"/>.</returns>
     public static DashboardSessionAdminResult Fail(string message)
     {
         return new DashboardSessionAdminResult(false, message);

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSessionAdminService.cs

@@ -93,10 +93,6 @@ public sealed class DashboardSessionAdminService(
         }
         catch (Exception exception)
         {
-            // Server-050: any non-SessionManagerException (e.g. an IOException or
-            // InvalidOperationException from the session DisposeAsync / pipe teardown
-            // path) used to propagate raw into Blazor's error boundary. Convert it to
-            // a friendly failure so the Razor pages see only DashboardSessionAdminResult.
             _logger.LogWarning(
                 exception,
                 "Dashboard admin {Actor} close failed unexpectedly for session {SessionId}.",
@@ -162,12 +158,6 @@ public sealed class DashboardSessionAdminService(
         }
         catch (Exception exception)
         {
-            // Server-050: any non-SessionManagerException (e.g. an IOException from
-            // worker pipe teardown surfacing through session.DisposeAsync, or an
-            // InvalidOperationException from a corrupted worker handle) used to
-            // propagate raw into Blazor's error boundary. Convert it to a friendly
-            // failure so the page renders the ResultMessage rather than the circuit
-            // error page.
             _logger.LogWarning(
                 exception,
                 "Dashboard admin {Actor} kill failed unexpectedly for session {SessionId}.",

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSnapshotService.cs

@@ -35,7 +35,7 @@ public sealed class DashboardSnapshotService : IDashboardSnapshotService
     // sequence means the breakdown is unchanged and can be reused — keeping the ~1s snapshot tick
     // O(1) for Galaxy. The summary's cheap volatile fields (status, timestamps, last error, counts)
     // are NOT memoized: the library mutates them in place at the same sequence on steady-state ticks
-    // and on refresh failure, so they are copied fresh on every snapshot (see Server-059).
+    // and on refresh failure, so they are copied fresh on every snapshot.
     private GalaxyBreakdownCache? _galaxyBreakdownCache;
 
     /// <summary>Initializes a new instance of the DashboardSnapshotService class.</summary>
@@ -72,10 +72,7 @@ public sealed class DashboardSnapshotService : IDashboardSnapshotService
         _logger = logger ?? NullLogger<DashboardSnapshotService>.Instance;
     }
 
-    /// <summary>
-    /// Gets a current dashboard snapshot of gateway state.
-    /// </summary>
-    /// <returns>Dashboard snapshot.</returns>
+    /// <inheritdoc />
     public DashboardSnapshot GetSnapshot()
     {
         DateTimeOffset generatedAt = _timeProvider.GetUtcNow();
@@ -133,11 +130,7 @@ public sealed class DashboardSnapshotService : IDashboardSnapshotService
 
     private sealed record GalaxyBreakdownCache(long Sequence, GalaxyObjectBreakdown Breakdown);
 
-    /// <summary>
-    /// Watches dashboard snapshots at regular intervals asynchronously.
-    /// </summary>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>Async enumerable of dashboard snapshots.</returns>
+    /// <inheritdoc />
     public async IAsyncEnumerable<DashboardSnapshot> WatchSnapshotsAsync(
         [EnumeratorCancellation] CancellationToken cancellationToken)
     {

src/ZB.MOM.WW.MxGateway.Server/Dashboard/HubTokenService.cs

@@ -12,7 +12,7 @@ namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
 /// protector; no separate signing keys are configured.
 /// </summary>
 /// <remarks>
-/// Server-043: this service is registered as a singleton in
+/// This service is registered as a singleton in
 /// <see cref="DashboardServiceCollectionExtensions.AddGatewayDashboard"/> and
 /// is shared by two consumer scopes: <c>DashboardHubConnectionFactory</c>
 /// (scoped, per-circuit; calls <see cref="Issue"/> from the cookie-authenticated
@@ -40,6 +40,7 @@ public sealed class HubTokenService
 
     /// <summary>Issues a bearer token carrying the user's identity and roles.</summary>
     /// <param name="user">The claims principal representing the user.</param>
+    /// <returns>The data-protected bearer token string.</returns>
     public string Issue(ClaimsPrincipal user)
     {
         ArgumentNullException.ThrowIfNull(user);
@@ -52,6 +53,7 @@ public sealed class HubTokenService
 
     /// <summary>Validates a token and returns the equivalent claims principal; null when invalid or expired.</summary>
     /// <param name="token">The token string to validate.</param>
+    /// <returns>The reconstructed <see cref="ClaimsPrincipal"/>, or <see langword="null"/> when the token is missing, invalid, or expired.</returns>
     public ClaimsPrincipal? Validate(string? token)
     {
         if (string.IsNullOrEmpty(token))
@@ -67,11 +69,6 @@ public sealed class HubTokenService
                 return null;
             }
 
-            // Server-039: reject a token whose payload carries no caller
-            // identity. A null/empty Name AND NameIdentifier would otherwise
-            // produce a principal that satisfies IsAuthenticated and IsInRole
-            // checks without any associated user, because the AuthenticationType
-            // (the HubToken scheme) is non-empty.
             if (string.IsNullOrEmpty(payload.Name) && string.IsNullOrEmpty(payload.NameIdentifier))
             {
                 return null;

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Hubs/DashboardEventBroadcaster.cs

@@ -14,9 +14,7 @@ public sealed class DashboardEventBroadcaster(
     IHubContext<EventsHub> hubContext,
     ILogger<DashboardEventBroadcaster> logger) : IDashboardEventBroadcaster
 {
-    /// <summary>Publishes an MX event to connected dashboard clients.</summary>
-    /// <param name="sessionId">The session identifier.</param>
-    /// <param name="mxEvent">The MX event to publish.</param>
+    /// <inheritdoc />
     public void Publish(string sessionId, MxEvent mxEvent)
     {
         if (string.IsNullOrEmpty(sessionId) || mxEvent is null)

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Hubs/DashboardSnapshotPublisher.cs

@@ -9,7 +9,7 @@ namespace ZB.MOM.WW.MxGateway.Server.Dashboard.Hubs;
 /// gateway process; clients listen via the hub.
 /// </summary>
 /// <remarks>
-/// Server-042: <see cref="ExecuteAsync"/> wraps the snapshot subscription in
+/// <see cref="ExecuteAsync"/> wraps the snapshot subscription in
 /// a reconnect loop with a configurable retry delay (5s by default,
 /// mirroring <see cref="AlarmsHubPublisher"/>). A transient failure inside
 /// <see cref="IDashboardSnapshotService.WatchSnapshotsAsync"/> — e.g. a

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Hubs/EventsHub.cs

@@ -27,7 +27,7 @@ public sealed class EventsHub : Hub
     /// client.
     /// </summary>
     /// <remarks>
-    /// Server-038: in v1 the hub-level <see cref="AuthorizeAttribute"/>
+    /// In v1 the hub-level <see cref="AuthorizeAttribute"/>
     /// (<c>HubClientsPolicy</c>) only checks that the caller carries one of
     /// the dashboard roles (Admin or Viewer); both roles may subscribe to
     /// any session id they choose. This is acceptable today because (a) the
@@ -43,6 +43,7 @@ public sealed class EventsHub : Hub
     /// dedicated authorization policy applied to the hub method itself.
     /// </remarks>
     /// <param name="sessionId">Session id to subscribe the caller to.</param>
+    /// <returns>A task representing the subscription operation.</returns>
     public Task SubscribeSession(string sessionId)
     {
         if (string.IsNullOrWhiteSpace(sessionId))

src/ZB.MOM.WW.MxGateway.Server/Dashboard/IDashboardAuthenticator.cs

@@ -11,6 +11,7 @@ public interface IDashboardAuthenticator
     /// <param name="username">Username to authenticate.</param>
     /// <param name="password">Password to authenticate.</param>
     /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
+    /// <returns>The authentication result.</returns>
     Task<DashboardAuthenticationResult> AuthenticateAsync(
         string? username,
         string? password,

src/ZB.MOM.WW.MxGateway.Server/Dashboard/IDashboardBrowseService.cs

@@ -12,11 +12,13 @@ public interface IDashboardBrowseService
 {
     /// <summary>Returns root browse nodes (objects with no parent).</summary>
     /// <param name="filter">Filter arguments forwarded to the projector.</param>
+    /// <returns>The root-level browse nodes and the cache sequence they were projected from.</returns>
     BrowseLevelResult GetRoots(BrowseFilterArgs filter);
 
     /// <summary>Returns the direct children of the given parent gobject id.</summary>
     /// <param name="parentGobjectId">The Galaxy gobject id of the parent to expand.</param>
     /// <param name="filter">Filter arguments forwarded to the projector.</param>
+    /// <returns>The child browse nodes for the requested parent and the cache sequence they were projected from.</returns>
     BrowseLevelResult GetChildren(int parentGobjectId, BrowseFilterArgs filter);
 
     /// <summary>Current Galaxy cache sequence. Bumps after each successful refresh.</summary>

src/ZB.MOM.WW.MxGateway.Server/Dashboard/IDashboardSnapshotService.cs

@@ -8,11 +8,13 @@ public interface IDashboardSnapshotService
     /// <summary>
     /// Gets the current dashboard snapshot.
     /// </summary>
+    /// <returns>The current dashboard snapshot.</returns>
     DashboardSnapshot GetSnapshot();
 
     /// <summary>
     /// Watches for changes to the dashboard state as an async enumerable.
     /// </summary>
     /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
+    /// <returns>An asynchronous stream of dashboard snapshots.</returns>
     IAsyncEnumerable<DashboardSnapshot> WatchSnapshotsAsync(CancellationToken cancellationToken);
 }