Add AGENTS.md with comprehensive build and test documentation

AGENTS.md

@@ -0,0 +1,74 @@
+# Steeltoe Build and Test Guide for Developers and CI/CD Agents
+
+This document provides essential guidelines for working with the Steeltoe codebase. For detailed build and test procedures, refer to the [GitHub workflows](.github/workflows/) which serve as the source of truth.
+
+## General Guidelines
+
+### Code Review and Suggestions
+- Only make high confidence suggestions when reviewing code changes.
+- Always use the latest stable version of C#.
+- Never add or change `global.json` unless explicitly asked to.
+- Never change `NuGet.config` files unless explicitly asked to.
+
+### Null Handling
+- Declare variables non-nullable, and check for null at public API entry points.
+- Trust the C# null annotations and don't add null checks when the type system says a value cannot be null.
+
+### Writing Tests
+- Do not emit "Act", "Arrange" or "Assert" comments in test code.
+- Tests should pass before committing and pushing changes.
+- When possible, code coverage levels should be increased or at least maintained.
+
+## Prerequisites
+
+- **.NET SDK 10.0** (latest patch version)
+- **.NET Runtime 8.0** (latest patch version)
+- **.NET Runtime 9.0** (latest patch version)
+
+Verify your installation:
+```bash
+dotnet --list-sdks
+dotnet --list-runtimes
+```
+
+## Quick Start
+
+### Build the Solution
+
+```bash
+dotnet restore src/Steeltoe.All.sln /p:Configuration=Release --verbosity minimal
+dotnet build src/Steeltoe.All.sln --no-restore --configuration Release --verbosity minimal
+```
+
+### Run Tests
+
+For detailed test procedures including environment-specific filters, test categories, and coverage collection, see [`.github/workflows/Steeltoe.All.yml`](.github/workflows/Steeltoe.All.yml).
+
+Quick test command:
+```bash
+dotnet test src/Steeltoe.All.sln --framework net10.0 --no-build --configuration Release
+```
+
+**Important context for agents:**
+- Tests run on multiple frameworks: net8.0, net9.0, and net10.0
+- Tests use xUnit trait categories: `Integration` (requires Docker services), `MemoryDumps` (generates memory dumps), and `SkipOnMacOS` (platform-specific)
+- Integration tests require Docker and are primarily designed for Linux CI environments
+- When writing tests, use appropriate categories: `[Trait("Category", "Integration")]` for tests requiring external services
+
+## Code Style Validation
+
+Steeltoe uses ReSharper/Rider code cleanup tools via `regitlint` to enforce consistent code style. The CI workflow (`.github/workflows/verify-code-style.yml`) automatically verifies code style on all pull requests.
+
+To run code cleanup locally:
+```powershell
+./cleanupcode.ps1
+```
+
+If your PR fails the code style check, run `cleanupcode.ps1` locally and commit the changes.
+
+## Additional Resources
+
+- [Steeltoe Documentation](https://steeltoe.io/)
+- [Contributing Guidelines](https://github.com/SteeltoeOSS/Steeltoe/wiki)
+- [CI Workflow](.github/workflows/Steeltoe.All.yml)
+- [Code Style Workflow](.github/workflows/verify-code-style.yml)

src/Management/src/Endpoint/Actuators/RouteMappings/RouteMappingsEndpointMiddleware.cs

@@ -2,6 +2,9 @@
 // The .NET Foundation licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information.
 
+using System.Text.Encodings.Web;
+using System.Text.Json;
+using Microsoft.AspNetCore.Http;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
 using Steeltoe.Management.Endpoint.Actuators.RouteMappings.ResponseTypes;
@@ -17,8 +20,30 @@ internal sealed class RouteMappingsEndpointMiddleware(
     IRouteMappingsEndpointHandler endpointHandler, IOptionsMonitor<ManagementOptions> managementOptionsMonitor, ILoggerFactory loggerFactory)
     : EndpointMiddleware<object?, RouteMappingsResponse>(endpointHandler, managementOptionsMonitor, loggerFactory)
 {
+    private JsonSerializerOptions? _serializerOptions;
+
     protected override async Task<RouteMappingsResponse> InvokeEndpointHandlerAsync(object? request, CancellationToken cancellationToken)
     {
         return await EndpointHandler.InvokeAsync(request, cancellationToken);
     }
+
+    protected override async Task WriteResponseAsync(RouteMappingsResponse response, HttpContext httpContext, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(httpContext);
+
+        if (Equals(response, null))
+        {
+            return;
+        }
+
+        httpContext.Response.Headers.Append("Content-Type", ContentType);
+
+        // Use UnsafeRelaxedJsonEscaping to make generic method signatures human-readable (e.g., backticks in generic type names).
+        _serializerOptions ??= new JsonSerializerOptions(ManagementOptionsMonitor.CurrentValue.SerializerOptions)
+        {
+            Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
+        };
+
+        await JsonSerializer.SerializeAsync(httpContext.Response.Body, response, _serializerOptions, cancellationToken);
+    }
 }

src/Management/src/Endpoint/Configuration/ConfigureManagementOptions.cs

@@ -2,7 +2,6 @@
 // The .NET Foundation licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information.
 
-using System.Text.Encodings.Web;
 using System.Text.Json.Serialization;
 using Microsoft.Extensions.Configuration;
 using Steeltoe.Common.Json;
@@ -54,10 +53,6 @@ private static void ConfigureSerializerOptions(ManagementOptions options)
     {
         options.SerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
 
-        // This was added initially for the route mappings actuator, to make generic method signatures human-readable,
-        // but may affect other endpoints too. Removing this is a breaking change.
-        options.SerializerOptions.Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping;
-
         options.SerializerOptions.AddJsonIgnoreEmptyCollection();
 
         foreach (string converterTypeName in options.CustomJsonConverters)

src/Management/test/Endpoint.Test/ManagementOptionsTest.cs

@@ -3,7 +3,6 @@
 // See the LICENSE file in the project root for more information.
 
 using System.Globalization;
-using System.Text.Encodings.Web;
 using System.Text.Json;
 using System.Text.Json.Serialization;
 using Microsoft.Extensions.Configuration;
@@ -27,8 +26,7 @@ public sealed class ManagementOptionsTest
         {
             new JsonStringEnumConverter()
         },
-        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
-        Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
     }.AddJsonIgnoreEmptyCollection();
 
     [Fact]