docs: complete XML doc coverage (returns, summaries, inheritdoc)

Resolve all 622 issues flagged by the enhanced CommentChecker: add missing
<returns> tags (incl. the standard phrasing on non-generic Task methods),
add missing <summary> tags, and replace misused/redundant <inheritdoc/> on
members that override or implement nothing with real documentation.
Documentation-only — no behavior change; solution builds clean.

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/ApiMethodCommands.cs

@@ -13,6 +13,7 @@ public static class ApiMethodCommands
     /// <param name="formatOption">Global option for the output format.</param>
     /// <param name="usernameOption">Global option for the authentication username.</param>
     /// <param name="passwordOption">Global option for the authentication password.</param>
+    /// <returns>The configured <c>api-method</c> command with all subcommands registered.</returns>
     public static Command Build(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
     {
         var command = new Command("api-method") { Description = "Manage inbound API methods" };

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/AuditCommands.cs

@@ -18,6 +18,7 @@ public static class AuditCommands
     /// <param name="formatOption">Global <c>--format</c> option for output format.</param>
     /// <param name="usernameOption">Global <c>--username</c> option for authentication.</param>
     /// <param name="passwordOption">Global <c>--password</c> option for authentication.</param>
+    /// <returns>The configured <c>audit</c> <see cref="Command"/> with all sub-commands attached.</returns>
     public static Command Build(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
     {
         var command = new Command("audit") { Description = "Query and export the centralized audit log" };

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/AuditExportHelpers.cs

@@ -74,6 +74,7 @@ public static class AuditExportHelpers
     /// </summary>
     /// <param name="args">The export arguments containing filters and format.</param>
     /// <param name="now">The current time for resolving relative time specifications.</param>
+    /// <returns>The full query string (including the leading <c>?</c>) for the export endpoint.</returns>
     public static string BuildQueryString(AuditExportArgs args, DateTimeOffset now)
     {
         var parts = new List<string>();
@@ -116,6 +117,7 @@ public static class AuditExportHelpers
     /// <param name="args">The export arguments containing filters and output file path.</param>
     /// <param name="output">Text writer for command output messages.</param>
     /// <param name="now">The current time for resolving relative time specifications.</param>
+    /// <returns>0 on success, 1 on general error, or 2 on authorization failure.</returns>
     public static async Task<int> RunExportAsync(
         ManagementHttpClient client, AuditExportArgs args, TextWriter output, DateTimeOffset now)
     {
@@ -178,6 +180,8 @@ public static class AuditExportHelpers
     /// to extract the <c>code</c> field. Returns null if the body is empty, not valid JSON, or
     /// has no <c>code</c> property — callers fall back to "ERROR" in that case.
     /// </summary>
+    /// <param name="body">The HTTP response body string to parse for an error code.</param>
+    /// <returns>The <c>code</c> string from the JSON error envelope, or null if absent or unparseable.</returns>
     internal static string? TryExtractErrorCode(string body)
     {
         if (string.IsNullOrWhiteSpace(body))

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/AuditFormatter.cs

@@ -43,6 +43,7 @@ public static class AuditFormatterFactory
     /// </summary>
     /// <param name="format">Format name; <c>table</c> selects the table formatter, any other value selects JSONL.</param>
     /// <param name="notices">Writer for notice messages emitted during formatting.</param>
+    /// <returns>The <see cref="IAuditFormatter"/> appropriate for the requested format.</returns>
     public static IAuditFormatter Create(string format, TextWriter notices)
     {
         if (string.Equals(format, "table", StringComparison.OrdinalIgnoreCase))

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/AuditLogCommands.cs

@@ -50,6 +50,7 @@ public static class AuditLogCommands
     /// <param name="formatOption">Global output format option.</param>
     /// <param name="usernameOption">Global username option.</param>
     /// <param name="passwordOption">Global password option.</param>
+    /// <returns>The configured <c>audit-config</c> command with all sub-commands registered.</returns>
     public static Command Build(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
     {
         var command = new Command("audit-config") { Description = "Query the configuration-change audit log" };

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/AuditQueryHelpers.cs

@@ -61,6 +61,7 @@ public static class AuditQueryHelpers
     /// <param name="spec">The time specification string.</param>
     /// <param name="now">The current time used as reference for relative specs.</param>
     /// <exception cref="FormatException">The spec is neither a known relative form nor a parseable ISO-8601 timestamp.</exception>
+    /// <returns>The resolved absolute <see cref="DateTimeOffset"/> in UTC.</returns>
     public static DateTimeOffset ResolveTimeSpec(string spec, DateTimeOffset now)
     {
         if (string.IsNullOrWhiteSpace(spec))
@@ -103,6 +104,7 @@ public static class AuditQueryHelpers
     /// <param name="now">The current time for resolving relative time specs.</param>
     /// <param name="afterOccurredAtUtc">Optional keyset cursor timestamp.</param>
     /// <param name="afterEventId">Optional keyset cursor event ID.</param>
+    /// <returns>A URL query string (starting with <c>?</c>) containing the encoded filter parameters, or an empty string if no parameters are set.</returns>
     public static string BuildQueryString(
         AuditQueryArgs args, DateTimeOffset now, DateTimeOffset? afterOccurredAtUtc, string? afterEventId)
     {
@@ -169,6 +171,7 @@ public static class AuditQueryHelpers
     /// <param name="formatter">The audit result formatter.</param>
     /// <param name="output">The output writer for results.</param>
     /// <param name="now">The current time for resolving relative time specs.</param>
+    /// <returns>A task that resolves to <c>0</c> on success, <c>1</c> on HTTP/transport error, or <c>2</c> on authorization failure.</returns>
     public static async Task<int> RunQueryAsync(
         ManagementHttpClient client,
         AuditQueryArgs args,

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/AuditVerifyChainHelpers.cs

@@ -14,6 +14,7 @@ public static class AuditVerifyChainHelpers
     /// with a real month (01-12). A malformed month (e.g. <c>2026-13</c>) is rejected.
     /// </summary>
     /// <param name="month">The month string to validate in YYYY-MM format.</param>
+    /// <returns><c>true</c> if the string is a well-formed YYYY-MM value with a real month; otherwise <c>false</c>.</returns>
     public static bool IsValidMonth(string? month)
         => !string.IsNullOrWhiteSpace(month)
            && DateTime.TryParseExact(month, "yyyy-MM", CultureInfo.InvariantCulture,

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/BundleCommands.cs

@@ -307,6 +307,13 @@ public static class BundleCommands
     // for the post-write summary line.
     internal const int Base64StreamChunkChars = 1024 * 1024; // 1 MB of base64 chars ≈ 768 KB decoded
 
+    /// <summary>
+    /// Decodes a base64 string into <paramref name="outputPath"/> in chunked fashion to avoid
+    /// large intermediate allocations. Returns the total number of decoded bytes written.
+    /// </summary>
+    /// <param name="base64">The base64-encoded content to decode and write.</param>
+    /// <param name="outputPath">Destination file path; created or overwritten.</param>
+    /// <returns>Total number of bytes written to the output file.</returns>
     internal static long StreamBase64ToFile(string base64, string outputPath)
     {
         if (base64 is null) throw new ArgumentNullException(nameof(base64));

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/CliOptions.cs

@@ -17,6 +17,7 @@ internal static class CliOptions
     /// typo (e.g. <c>--format tabel</c>) is rejected with a clear parse error rather
     /// than silently falling through to JSON.
     /// </summary>
+    /// <returns>The configured <c>--format</c> option constrained to "json" or "table".</returns>
     internal static Option<string> CreateFormatOption()
     {
         var formatOption = new Option<string>("--format")

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/CommandHelpers.cs

@@ -30,6 +30,7 @@ internal static class CommandHelpers
     /// (<see cref="IsAuthorizationFailure"/>) is preserved on the error path either way,
     /// closing CLI-017's regression.
     /// </param>
+    /// <returns>A task that resolves to the process exit code (0 = success, 1 = error, 2 = authorization failure).</returns>
     internal static async Task<int> ExecuteCommandAsync(
         ParseResult result,
         Option<string> urlOption,
@@ -110,6 +111,7 @@ internal static class CommandHelpers
     /// <param name="result">Parsed command-line result.</param>
     /// <param name="formatOption">The <c>--format</c> option definition.</param>
     /// <param name="config">Loaded CLI configuration providing the default format fallback.</param>
+    /// <returns>The resolved format string (e.g. <c>"json"</c> or <c>"table"</c>).</returns>
     internal static string ResolveFormat(ParseResult result, Option<string> formatOption, CliConfig config)
     {
         // GetResult returns non-null only when the option was actually present on the
@@ -130,6 +132,7 @@ internal static class CommandHelpers
     /// </summary>
     /// <param name="commandLineValue">Value supplied on the command line, or null if absent.</param>
     /// <param name="envValue">Fallback value from the config file or environment variable.</param>
+    /// <returns>The command-line value when non-empty; otherwise the environment fallback (may be null).</returns>
     internal static string? ResolveCredential(string? commandLineValue, string? envValue)
         => string.IsNullOrWhiteSpace(commandLineValue) ? envValue : commandLineValue;
 
@@ -140,6 +143,7 @@ internal static class CommandHelpers
     /// an unhandled <see cref="UriFormatException"/>.
     /// </summary>
     /// <param name="url">URL string to validate.</param>
+    /// <returns><c>true</c> when the URL is an absolute http or https URL; otherwise <c>false</c>.</returns>
     internal static bool IsValidManagementUrl(string? url)
     {
         if (string.IsNullOrWhiteSpace(url))
@@ -154,6 +158,7 @@ internal static class CommandHelpers
     /// </summary>
     /// <param name="response">Response received from the management API.</param>
     /// <param name="format">Output format (<c>json</c> or <c>table</c>).</param>
+    /// <returns>The process exit code (0 = success, 1 = error, 2 = authorization failure).</returns>
     internal static int HandleResponse(ManagementResponse response, string format)
     {
         if (response.JsonData != null)
@@ -192,6 +197,8 @@ internal static class CommandHelpers
     /// both channels are honoured. (Authentication failure — HTTP 401 / bad credentials
     /// — is deliberately <em>not</em> treated as authorization failure; it is exit 1.)
     /// </summary>
+    /// <param name="response">The management response to inspect for authorization failure signals.</param>
+    /// <returns><c>true</c> when the response signals an authorization failure (HTTP 403 or FORBIDDEN/UNAUTHORIZED code).</returns>
     internal static bool IsAuthorizationFailure(ManagementResponse response)
     {
         if (response.StatusCode == 403)

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/DataConnectionCommands.cs

@@ -13,6 +13,7 @@ public static class DataConnectionCommands
     /// <param name="formatOption">Global output format option.</param>
     /// <param name="usernameOption">Global username option.</param>
     /// <param name="passwordOption">Global password option.</param>
+    /// <returns>The configured <c>data-connection</c> <see cref="Command"/> with all subcommands registered.</returns>
     public static Command Build(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
     {
         var command = new Command("data-connection") { Description = "Manage data connections" };

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/DebugCommands.cs

@@ -15,6 +15,7 @@ public static class DebugCommands
     /// <param name="formatOption">Shared output format option.</param>
     /// <param name="usernameOption">Shared username option for authentication.</param>
     /// <param name="passwordOption">Shared password option for authentication.</param>
+    /// <returns>The configured <c>debug</c> command with snapshot and stream subcommands registered.</returns>
     public static Command Build(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
     {
         var command = new Command("debug") { Description = "Runtime debugging" };

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/DebugStreamHelpers.cs

@@ -27,6 +27,7 @@ internal static class DebugStreamHelpers
     /// </summary>
     /// <param name="ex">The exception thrown by HubConnection.StartAsync.</param>
     /// <param name="cancellationRequested">True when the user requested cancellation (Ctrl+C) before the exception was thrown.</param>
+    /// <returns>A <see cref="ConnectFailure"/> describing whether the failure was a cancellation and the appropriate exit code.</returns>
     internal static ConnectFailure ClassifyConnectFailure(Exception ex, bool cancellationRequested)
     {
         if (cancellationRequested && ex is OperationCanceledException)
@@ -43,6 +44,7 @@ internal static class DebugStreamHelpers
     /// result is ever produced (pure Ctrl+C), the stream ended gracefully — exit 0.
     /// </summary>
     /// <param name="exitTask">The task whose result is the intended exit code, set by OnStreamTerminated or the Closed handler.</param>
+    /// <returns>A task that resolves to the process exit code (0 for graceful exit or pure Ctrl+C, non-zero for error).</returns>
     internal static async Task<int> ResolveStreamExitCodeAsync(Task<int> exitTask)
     {
         if (exitTask.IsCompletedSuccessfully)

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/DeployCommands.cs

@@ -13,6 +13,7 @@ public static class DeployCommands
     /// <param name="formatOption">Global output format option.</param>
     /// <param name="usernameOption">Global username option.</param>
     /// <param name="passwordOption">Global password option.</param>
+    /// <returns>The configured <c>deploy</c> <see cref="Command"/> with all sub-commands attached.</returns>
     public static Command Build(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
     {
         var command = new Command("deploy") { Description = "Deployment operations" };

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/ExternalSystemCommands.cs

@@ -13,6 +13,7 @@ public static class ExternalSystemCommands
     /// <param name="formatOption">Global option for the output format.</param>
     /// <param name="usernameOption">Global option for the authentication username.</param>
     /// <param name="passwordOption">Global option for the authentication password.</param>
+    /// <returns>The fully configured <c>external-system</c> <see cref="Command"/> with all subcommands registered.</returns>
     public static Command Build(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
     {
         var command = new Command("external-system") { Description = "Manage external systems" };

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/HealthCommands.cs

@@ -13,6 +13,7 @@ public static class HealthCommands
     /// <param name="formatOption">Global <c>--format</c> option for output format.</param>
     /// <param name="usernameOption">Global <c>--username</c> option for authentication.</param>
     /// <param name="passwordOption">Global <c>--password</c> option for authentication.</param>
+    /// <returns>The configured <c>health</c> command with all sub-commands registered.</returns>
     public static Command Build(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
     {
         var command = new Command("health") { Description = "Health monitoring" };

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/NotificationCommands.cs

@@ -13,6 +13,7 @@ public static class NotificationCommands
     /// <param name="formatOption">Global <c>--format</c> option for output format.</param>
     /// <param name="usernameOption">Global <c>--username</c> option for authentication.</param>
     /// <param name="passwordOption">Global <c>--password</c> option for authentication.</param>
+    /// <returns>The configured <c>notification</c> command with all sub-commands registered.</returns>
     public static Command Build(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
     {
         var command = new Command("notification") { Description = "Manage notification lists" };
@@ -131,6 +132,7 @@ public static class NotificationCommands
     /// null when omitted so the server-side handler preserves the existing values.
     /// </summary>
     /// <param name="result">The parsed command-line result from the <c>smtp update</c> invocation.</param>
+    /// <returns>An <see cref="UpdateSmtpConfigCommand"/> populated from the parsed result.</returns>
     internal static UpdateSmtpConfigCommand BuildUpdateSmtpConfigCommand(ParseResult result)
     {
         var id = result.GetValue(SmtpIdOption);

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/SecurityCommands.cs

@@ -13,6 +13,7 @@ public static class SecurityCommands
     /// <param name="formatOption">Shared output format option.</param>
     /// <param name="usernameOption">Shared username option for authentication.</param>
     /// <param name="passwordOption">Shared password option for authentication.</param>
+    /// <returns>The configured <c>security</c> command with all subcommands attached.</returns>
     public static Command Build(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
     {
         var command = new Command("security") { Description = "Manage security settings" };
@@ -125,6 +126,7 @@ public static class SecurityCommands
     /// The advisory line is written to stderr so that piping stdout captures only the token.
     /// </summary>
     /// <param name="json">The JSON success body returned by the management API.</param>
+    /// <returns>Exit code 0.</returns>
     internal static int PrintCreatedKey(string json)
     {
         using var doc = System.Text.Json.JsonDocument.Parse(json);

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/SiteCommands.cs

@@ -13,6 +13,7 @@ public static class SiteCommands
     /// <param name="formatOption">Global output format option.</param>
     /// <param name="usernameOption">Global username option.</param>
     /// <param name="passwordOption">Global password option.</param>
+    /// <returns>The configured <c>site</c> command with all subcommands attached.</returns>
     public static Command Build(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
     {
         var command = new Command("site") { Description = "Manage sites" };

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/TemplateCommands.cs

@@ -11,6 +11,7 @@ public static class TemplateCommands
     /// <param name="formatOption">Shared output format option.</param>
     /// <param name="usernameOption">Shared username option for authentication.</param>
     /// <param name="passwordOption">Shared password option for authentication.</param>
+    /// <returns>The fully configured <c>template</c> command with all its subcommands.</returns>
     public static Command Build(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
     {
         var command = new Command("template") { Description = "Manage templates" };