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.InboundAPI/EndpointExtensions.cs

@@ -53,6 +53,7 @@ public static class EndpointExtensions
 
     /// <summary>Registers the <c>POST /api/{methodName}</c> inbound API endpoint with the active-node gate and body-size filter applied.</summary>
     /// <param name="endpoints">The route builder to add the endpoint to.</param>
+    /// <returns>The same <paramref name="endpoints"/> instance for chaining.</returns>
     public static IEndpointRouteBuilder MapInboundAPI(this IEndpointRouteBuilder endpoints)
     {
         endpoints.MapPost("/api/{methodName}", HandleInboundApiRequest)

src/ZB.MOM.WW.ScadaBridge.InboundAPI/ForbiddenApiChecker.cs

@@ -96,6 +96,7 @@ public static class ForbiddenApiChecker
     /// An empty list means the script is acceptable.
     /// </summary>
     /// <param name="scriptCode">The C# script source to analyse.</param>
+    /// <returns>A list of trust-model violation messages; empty if the script is clean.</returns>
     public static IReadOnlyList<string> FindViolations(string scriptCode)
     {
         if (string.IsNullOrWhiteSpace(scriptCode))

src/ZB.MOM.WW.ScadaBridge.InboundAPI/IInstanceRouter.cs

@@ -15,6 +15,7 @@ public interface IInstanceRouter
     /// <param name="siteId">Target site identifier.</param>
     /// <param name="request">The call request to route.</param>
     /// <param name="cancellationToken">Cancellation token for the routed call.</param>
+    /// <returns>A task that resolves to the call response from the target site.</returns>
     Task<RouteToCallResponse> RouteToCallAsync(
         string siteId, RouteToCallRequest request, CancellationToken cancellationToken);
 
@@ -22,6 +23,7 @@ public interface IInstanceRouter
     /// <param name="siteId">Target site identifier.</param>
     /// <param name="request">The get-attributes request to route.</param>
     /// <param name="cancellationToken">Cancellation token for the routed call.</param>
+    /// <returns>A task that resolves to the get-attributes response from the target site.</returns>
     Task<RouteToGetAttributesResponse> RouteToGetAttributesAsync(
         string siteId, RouteToGetAttributesRequest request, CancellationToken cancellationToken);
 
@@ -29,6 +31,7 @@ public interface IInstanceRouter
     /// <param name="siteId">Target site identifier.</param>
     /// <param name="request">The set-attributes request to route.</param>
     /// <param name="cancellationToken">Cancellation token for the routed call.</param>
+    /// <returns>A task that resolves to the set-attributes response from the target site.</returns>
     Task<RouteToSetAttributesResponse> RouteToSetAttributesAsync(
         string siteId, RouteToSetAttributesRequest request, CancellationToken cancellationToken);
 }

src/ZB.MOM.WW.ScadaBridge.InboundAPI/InboundApiEndpointFilter.cs

@@ -40,6 +40,7 @@ public sealed class InboundApiEndpointFilter : IEndpointFilter
     /// <summary>Applies active-node gating and request body size checks before delegating to the next filter or handler.</summary>
     /// <param name="context">The endpoint filter invocation context containing the HTTP context and arguments.</param>
     /// <param name="next">The next filter or endpoint handler in the pipeline.</param>
+    /// <returns>A value task that resolves to the filter pipeline result, or an error result if gating fails.</returns>
     public async ValueTask<object?> InvokeAsync(
         EndpointFilterInvocationContext context,
         EndpointFilterDelegate next)

src/ZB.MOM.WW.ScadaBridge.InboundAPI/Middleware/AuditWriteMiddleware.cs

@@ -128,6 +128,7 @@ public sealed class AuditWriteMiddleware
     /// Executes the middleware: captures the request/response bodies and writes an inbound API audit event.
     /// </summary>
     /// <param name="ctx">The current HTTP context.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async Task InvokeAsync(HttpContext ctx)
     {
         var sw = Stopwatch.StartNew();
@@ -686,6 +687,7 @@ public sealed class AuditWriteMiddleware
         /// audit copy hit the cap. Returns <c>(null, false)</c> when no bytes
         /// were captured, mirroring the request-body empty contract.
         /// </summary>
+        /// <returns>A tuple of the captured body string (or <c>null</c> if nothing was captured) and a flag indicating whether the cap was exceeded.</returns>
         public (string? body, bool truncated) GetCapturedBody()
         {
             var length = (int)_captured.Length;

src/ZB.MOM.WW.ScadaBridge.InboundAPI/Middleware/AuditWriteMiddlewareExtensions.cs

@@ -19,6 +19,7 @@ public static class AuditWriteMiddlewareExtensions
     /// middleware runs.
     /// </summary>
     /// <param name="app">The application builder to add the middleware to.</param>
+    /// <returns>The same <paramref name="app"/> instance, for call chaining.</returns>
     public static IApplicationBuilder UseAuditWriteMiddleware(this IApplicationBuilder app)
     {
         ArgumentNullException.ThrowIfNull(app);

src/ZB.MOM.WW.ScadaBridge.InboundAPI/ParameterValidator.cs

@@ -15,6 +15,7 @@ public static class ParameterValidator
     /// </summary>
     /// <param name="body">The parsed JSON request body; null or undefined if no body was supplied.</param>
     /// <param name="parameterDefinitions">JSON-serialized list of <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.InboundApi.ParameterDefinition"/>; null or empty means no parameters are defined.</param>
+    /// <returns>A <see cref="ParameterValidationResult"/> with coerced parameter values on success, or an error message on failure.</returns>
     public static ParameterValidationResult Validate(
         JsonElement? body,
         string? parameterDefinitions)
@@ -161,6 +162,7 @@ public class ParameterValidationResult
     /// Creates a successful validation result with the given parameters.
     /// </summary>
     /// <param name="parameters">The validated and coerced parameter values.</param>
+    /// <returns>A <see cref="ParameterValidationResult"/> with <see cref="IsValid"/> set to <c>true</c>.</returns>
     public static ParameterValidationResult Valid(Dictionary<string, object?> parameters) =>
         new() { IsValid = true, Parameters = parameters };
 
@@ -168,6 +170,7 @@ public class ParameterValidationResult
     /// Creates a failed validation result with the given error message.
     /// </summary>
     /// <param name="message">Description of the validation failure.</param>
+    /// <returns>A <see cref="ParameterValidationResult"/> with <see cref="IsValid"/> set to <c>false</c>.</returns>
     public static ParameterValidationResult Invalid(string message) =>
         new() { IsValid = false, ErrorMessage = message };
 }

src/ZB.MOM.WW.ScadaBridge.InboundAPI/ReturnValueValidator.cs

@@ -28,6 +28,7 @@ public static class ReturnValueValidator
     /// </summary>
     /// <param name="resultJson">The JSON-serialized script return value to validate.</param>
     /// <param name="returnDefinition">JSON-serialized list of <see cref="ReturnFieldDefinition"/> entries, or null/empty to skip validation.</param>
+    /// <returns>A <see cref="ReturnValidationResult"/> indicating success or describing the first validation failure.</returns>
     public static ReturnValidationResult Validate(string? resultJson, string? returnDefinition)
     {
         if (string.IsNullOrWhiteSpace(returnDefinition))
@@ -144,10 +145,12 @@ public sealed class ReturnValidationResult
     public string ErrorMessage { get; private init; } = string.Empty;
 
     /// <summary>Returns a successful validation result.</summary>
+    /// <returns>A <see cref="ReturnValidationResult"/> with <see cref="IsValid"/> set to <c>true</c>.</returns>
     public static ReturnValidationResult Valid() => new() { IsValid = true };
 
     /// <summary>Returns a failed validation result with the specified error message.</summary>
     /// <param name="message">Human-readable description of the validation failure.</param>
+    /// <returns>A <see cref="ReturnValidationResult"/> with <see cref="IsValid"/> set to <c>false</c> and the given error message.</returns>
     public static ReturnValidationResult Invalid(string message) =>
         new() { IsValid = false, ErrorMessage = message };
 }

src/ZB.MOM.WW.ScadaBridge.InboundAPI/RouteHelper.cs

@@ -53,6 +53,7 @@ public class RouteHelper
     /// requires.
     /// </summary>
     /// <param name="deadlineToken">The executing method's timeout cancellation token to inherit for routed calls.</param>
+    /// <returns>A new <see cref="RouteHelper"/> inheriting the given deadline token.</returns>
     public RouteHelper WithDeadline(CancellationToken deadlineToken) =>
         new(_instanceLocator, _instanceRouter, deadlineToken, _parentExecutionId);
 
@@ -66,6 +67,7 @@ public class RouteHelper
     /// script context.
     /// </summary>
     /// <param name="parentExecutionId">The inbound request's execution id to stamp as the spawning parent on routed calls, or null for non-routed runs.</param>
+    /// <returns>A new <see cref="RouteHelper"/> carrying the given parent execution id.</returns>
     public RouteHelper WithParentExecutionId(Guid? parentExecutionId) =>
         new(_instanceLocator, _instanceRouter, _deadlineToken, parentExecutionId);
 
@@ -73,6 +75,7 @@ public class RouteHelper
     /// Creates a route target for the specified instance.
     /// </summary>
     /// <param name="instanceCode">The unique code of the instance to route calls to.</param>
+    /// <returns>A <see cref="RouteTarget"/> bound to the specified instance.</returns>
     public RouteTarget To(string instanceCode)
     {
         return new RouteTarget(
@@ -125,6 +128,7 @@ public class RouteTarget
     /// <param name="scriptName">Name of the script to call on the remote instance.</param>
     /// <param name="parameters">Optional parameters passed to the script; may be a dictionary or anonymous object.</param>
     /// <param name="cancellationToken">Optional cancellation token; defaults to the method deadline when not supplied.</param>
+    /// <returns>A task that resolves to the remote script's return value, or null.</returns>
     public async Task<object?> Call(
         string scriptName,
         object? parameters = null,
@@ -158,6 +162,7 @@ public class RouteTarget
     /// </summary>
     /// <param name="attributeName">Name of the attribute to read.</param>
     /// <param name="cancellationToken">Optional cancellation token; defaults to the method deadline.</param>
+    /// <returns>A task that resolves to the attribute value, or null if the key is absent.</returns>
     public async Task<object?> GetAttribute(
         string attributeName,
         CancellationToken cancellationToken = default)
@@ -171,6 +176,7 @@ public class RouteTarget
     /// </summary>
     /// <param name="attributeNames">Names of the attributes to read.</param>
     /// <param name="cancellationToken">Optional cancellation token; defaults to the method deadline.</param>
+    /// <returns>A task that resolves to a map of attribute names to their current values.</returns>
     public async Task<IReadOnlyDictionary<string, object?>> GetAttributes(
         IEnumerable<string> attributeNames,
         CancellationToken cancellationToken = default)
@@ -205,6 +211,7 @@ public class RouteTarget
     /// <param name="attributeName">Name of the attribute to write.</param>
     /// <param name="value">Value to set on the attribute.</param>
     /// <param name="cancellationToken">Optional cancellation token; defaults to the method deadline.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async Task SetAttribute(
         string attributeName,
         string value,
@@ -220,6 +227,7 @@ public class RouteTarget
     /// </summary>
     /// <param name="attributeValues">Map of attribute names to values to write.</param>
     /// <param name="cancellationToken">Optional cancellation token; defaults to the method deadline.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async Task SetAttributes(
         IReadOnlyDictionary<string, string> attributeValues,
         CancellationToken cancellationToken = default)

src/ZB.MOM.WW.ScadaBridge.InboundAPI/ServiceCollectionExtensions.cs

@@ -8,6 +8,7 @@ public static class ServiceCollectionExtensions
     /// Registers all inbound API services (script executor, route helper, and endpoint filter).
     /// </summary>
     /// <param name="services">The service collection to register into.</param>
+    /// <returns>The same <see cref="IServiceCollection"/> to allow chaining.</returns>
     public static IServiceCollection AddInboundAPI(this IServiceCollection services)
     {
         // Auth re-arch (C5): inbound authentication is handled by the shared