Merge remote-tracking branch 'origin/main' into feature/docs-mdx-skeletons

docs/api/openapi-discovery.md

@@ -22,3 +22,95 @@ Contracts:
 - `extensions` carries optional metadata for downstream tooling.
 
 Implementations (API Gateway / Console) should cache the response with `Cache-Control: max-age=300` and serve it alongside the aggregate spec artifact produced by the OAS CI workflow.
+
+---
+
+## Gateway OpenAPI Aggregation
+
+The Router Gateway dynamically aggregates OpenAPI documentation from connected microservices. This provides a unified API specification that updates automatically as services connect and disconnect.
+
+### Discovery Endpoint
+
+```http
+GET /.well-known/openapi
+```
+
+**Response:**
+```json
+{
+  "openapi_json": "/openapi.json",
+  "openapi_yaml": "/openapi.yaml",
+  "etag": "\"5d41402abc4b2a76b9719d911017c592\"",
+  "generated_at": "2025-01-15T10:30:00.0000000Z"
+}
+```
+
+### OpenAPI Endpoints
+
+| Endpoint | Format | Content-Type |
+|----------|--------|--------------|
+| `GET /openapi.json` | JSON | `application/json; charset=utf-8` |
+| `GET /openapi.yaml` | YAML | `application/yaml; charset=utf-8` |
+
+### HTTP Caching
+
+All OpenAPI endpoints support efficient caching:
+
+| Header | Value | Description |
+|--------|-------|-------------|
+| `Cache-Control` | `public, max-age=60` | Client-side cache TTL |
+| `ETag` | `"<hash>"` | Content hash for conditional requests |
+
+**Conditional Request:**
+```http
+GET /openapi.json
+If-None-Match: "5d41402abc4b2a76b9719d911017c592"
+```
+
+Returns `304 Not Modified` if content unchanged.
+
+### Security Schemes
+
+The Gateway generates two security schemes from endpoint claim requirements:
+
+#### BearerAuth
+```json
+{
+  "type": "http",
+  "scheme": "bearer",
+  "bearerFormat": "JWT",
+  "description": "JWT Bearer token authentication"
+}
+```
+
+#### OAuth2 (when endpoints have claims)
+```json
+{
+  "type": "oauth2",
+  "flows": {
+    "clientCredentials": {
+      "tokenUrl": "/auth/token",
+      "scopes": {
+        "billing:write": "Access scope: billing:write",
+        "inventory:read": "Access scope: inventory:read"
+      }
+    }
+  }
+}
+```
+
+### Schema Prefixing
+
+Schemas are prefixed with the service name to avoid collisions:
+
+- `billing` service + `CreateInvoiceRequest` type = `billing_CreateInvoiceRequest`
+
+### Configuration
+
+See [OpenAPI Aggregation](../modules/router/openapi-aggregation.md) for Gateway configuration options.
+
+### Related Documentation
+
+- [Schema Validation](../modules/router/schema-validation.md) - JSON Schema validation in microservices
+- [OpenAPI Aggregation](../modules/router/openapi-aggregation.md) - Gateway aggregation configuration
+- [Gateway OpenAPI](../modules/gateway/openapi.md) - Implementation architecture

docs/api/overview.md

@@ -5,6 +5,12 @@ Last updated: 2025-11-25 (Md.V docs stream)
 ## Scope
 Shared conventions for all StellaOps HTTP APIs. Service-specific schemas live under `src/Api/StellaOps.Api.OpenApi` and composed `out/api/stella.yaml`.
 
+## Related Documentation
+
+- [OpenAPI Discovery](openapi-discovery.md) - Discovery endpoints and aggregation
+- [Schema Validation](../modules/router/schema-validation.md) - JSON Schema validation for microservice endpoints
+- [OpenAPI Aggregation](../modules/router/openapi-aggregation.md) - Gateway OpenAPI document generation
+
 ## Authentication & tenancy
 - **Auth**: Bearer tokens (`Authorization: Bearer <token>`); service accounts must include `aud` for the target service.
 - **Tenancy**: Multi-tenant endpoints require `X-Stella-Tenant` (or embedded tenant in token claims). Requests without tenant fail with `403` + `error.code = TENANT_REQUIRED`.