Merge remote-tracking branch 'origin/main' into agent-3/issue-4-add-structured-logging-and-metrics-foundation

# Conflicts:
#	src/MxGateway.Server/GatewayApplication.cs
#	src/MxGateway.Tests/Gateway/GatewayApplicationTests.cs

docs/Contracts.md

@@ -0,0 +1,46 @@
+# Protobuf Contracts
+
+The contracts project contains the public gRPC API and the gateway-to-worker
+IPC messages. The `.proto` files are the source of truth; generated C# files are
+recreated by the contracts project build.
+
+## Files
+
+`src/MxGateway.Contracts/Protos/mxaccess_gateway.proto` defines the public
+`MxAccessGateway` gRPC service, command payloads, command replies, event DTOs,
+`MxValue`, `MxArray`, and `MxStatusProxy`.
+
+`src/MxGateway.Contracts/Protos/mxaccess_worker.proto` defines the named-pipe
+worker IPC envelope and control messages. It imports
+`mxaccess_gateway.proto` so the worker and gateway use the same command, reply,
+event, value, and status shapes.
+
+Generated C# output is written to `src/MxGateway.Contracts/Generated/`. Do not
+hand-edit generated files.
+
+## Generation
+
+Run the contracts build to regenerate C# protobuf and gRPC code:
+
+```bash
+dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj
+```
+
+Run the focused contract tests after changing either `.proto` file:
+
+```bash
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter ProtobufContractRoundTripTests
+```
+
+The full solution build also regenerates the C# contracts before compiling
+gateway and test projects:
+
+```bash
+dotnet build src/MxGateway.sln
+```
+
+## Related Documentation
+
+- [Gateway Process Detailed Design](./gateway-process-design.md)
+- [MXAccess Worker Instance Detailed Design](./mxaccess-worker-instance-design.md)
+- [Protobuf Style Guide](./style-guides/ProtobufStyleGuide.md)

docs/gateway-process-design.md

@@ -730,6 +730,18 @@ Suggested configuration shape:
 
 Do not scatter connection or path constants through implementation code.
 
+`MxGateway.Server` binds this section to `GatewayOptions` at startup and
+registers validation with `ValidateOnStart()`. Startup fails before the gateway
+begins serving traffic when required authentication settings are missing,
+timeouts or queue sizes are not positive, dashboard settings are malformed, or
+the configured worker protocol version does not match the contract version.
+
+The gateway exposes read-only effective settings through
+`IGatewayConfigurationProvider`. This projection is for dashboard settings and
+diagnostics, so it redacts secret-related fields such as
+`Authentication:PepperSecretName` and does not include raw API keys or key
+material.
+
 ## Galaxy Repository Metadata
 
 Galaxy hierarchy and tag metadata can be discovered through SQL Server when