docs consolidation work

docs/modules/router/aspnet-endpoint-bridge.md

@@ -781,6 +781,189 @@ endpoints:
 
 ---
 
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Endpoints Not Discovered
+
+**Symptom:** Gateway shows 0 endpoints for service, or specific endpoints missing.
+
+**Causes & Solutions:**
+
+| Cause | Solution |
+|-------|----------|
+| `UseStellaRouterBridge()` called before `MapControllers()` | Call `UseStellaRouterBridge()` after all endpoint registration |
+| Route filtered by `EndpointFilter` | Check filter logic, ensure endpoint matches |
+| Route filtered by `IncludePathPatterns` | Verify path pattern includes the endpoint |
+| Route filtered by `ExcludePathPatterns` | Verify endpoint isn't accidentally excluded |
+| Missing `[Authorize]` with `RequireExplicit` | Add authorization or change `MissingAuthorizationBehavior` |
+
+**Debug:**
+```csharp
+// Enable discovery logging
+builder.Logging.AddFilter("StellaOps.Microservice.AspNetCore", LogLevel.Debug);
+```
+
+#### 2. Authorization Claims Not Extracted
+
+**Symptom:** Endpoints registered but `RequiringClaims` is empty when it shouldn't be.
+
+**Causes & Solutions:**
+
+| Cause | Solution |
+|-------|----------|
+| `[Authorize]` without policy/roles | Add explicit policy or roles |
+| Policy not registered | Register policy with `AddAuthorization()` |
+| `AuthorizationMappingStrategy.YamlOnly` set | Use `Hybrid` or `AspNetMetadataOnly` |
+| Custom policy doesn't have claim requirements | Use claims-based policies |
+
+**Debug:**
+```csharp
+// Log authorization mapping
+var mapper = app.Services.GetRequiredService<IAuthorizationClaimMapper>();
+var result = await mapper.MapAsync(endpoint);
+Console.WriteLine($"Claims: {string.Join(", ", result.Claims)}");
+```
+
+#### 3. Request Dispatch Fails with 404
+
+**Symptom:** Gateway routes request but microservice returns 404.
+
+**Causes & Solutions:**
+
+| Cause | Solution |
+|-------|----------|
+| Path parameters not matched | Verify parameter names in route pattern |
+| Method mismatch | Verify HTTP method matches endpoint |
+| Route constraint rejected value | Use standard constraints that bridge supports |
+| Catch-all route not handled | Ensure `{**path}` is normalized correctly |
+
+**Debug:**
+```bash
+# Check registered endpoints
+curl http://localhost:5000/.well-known/stella-endpoints
+```
+
+#### 4. Model Binding Errors
+
+**Symptom:** Requests return 400 Bad Request with binding errors.
+
+**Causes & Solutions:**
+
+| Cause | Solution |
+|-------|----------|
+| `[FromBody]` type mismatch | Verify request body matches expected type |
+| Required parameter missing | Include all `[FromRoute]`/`[FromQuery]` parameters |
+| `[FromHeader]` not populated | Headers forwarded via `X-StellaOps-Header-*` |
+| Complex type not deserialized | Verify JSON serialization settings |
+
+**Debug:**
+```csharp
+// Enable model binding logging
+builder.Logging.AddFilter("Microsoft.AspNetCore.Mvc.ModelBinding", LogLevel.Debug);
+```
+
+#### 5. Identity Not Populated
+
+**Symptom:** `User.Identity` is null or claims missing in endpoint handler.
+
+**Causes & Solutions:**
+
+| Cause | Solution |
+|-------|----------|
+| Gateway not forwarding identity | Verify Gateway `identity-header-policy` configured |
+| Missing `X-StellaOps-UserId` header | Gateway must send identity headers |
+| `UseAuthentication()` not called | Call before `UseStellaRouterBridge()` |
+| Custom claims not mapped | Use `ClaimsPrincipalBuilder` for custom claims |
+
+**Debug:**
+```csharp
+app.MapGet("/debug/identity", (HttpContext ctx) =>
+    new {
+        IsAuthenticated = ctx.User.Identity?.IsAuthenticated,
+        Name = ctx.User.Identity?.Name,
+        Claims = ctx.User.Claims.Select(c => new { c.Type, c.Value })
+    });
+```
+
+#### 6. Performance Issues
+
+**Symptom:** High latency or memory usage.
+
+**Causes & Solutions:**
+
+| Cause | Solution |
+|-------|----------|
+| HttpContext allocation per request | Pool contexts (internal implementation) |
+| Large request bodies buffered | Use streaming endpoints for large payloads |
+| Discovery runs too frequently | Discovery runs once at startup; cache is stable |
+| Many endpoints slow startup | Discovery is O(n) but runs once |
+
+**Metrics to monitor:**
+- `stellaops_router_bridge_requests_total`
+- `stellaops_router_bridge_request_duration_seconds`
+- `stellaops_router_bridge_dispatch_errors_total`
+
+#### 7. YAML Override Not Applied
+
+**Symptom:** Claims from YAML file not appearing in endpoint registration.
+
+**Causes & Solutions:**
+
+| Cause | Solution |
+|-------|----------|
+| `YamlConfigPath` not set | Set `options.YamlConfigPath = "router.yaml"` |
+| File not found | Use absolute path or verify relative path |
+| Path pattern doesn't match | YAML paths are case-insensitive, verify pattern |
+| `AuthorizationMappingStrategy.AspNetMetadataOnly` | Use `YamlOnly` or `Hybrid` |
+
+**Example YAML:**
+```yaml
+# router.yaml
+endpoints:
+  - path: "/api/admin/**"
+    requiringClaims:
+      - type: "Role"
+        value: "admin"
+```
+
+### Diagnostic Endpoints
+
+The bridge adds optional diagnostic endpoints (development only):
+
+| Endpoint | Description |
+|----------|-------------|
+| `/.well-known/stella-endpoints` | Lists all discovered endpoints |
+| `/.well-known/stella-bridge-status` | Shows bridge configuration and health |
+
+Enable in development:
+```csharp
+builder.Services.AddStellaRouterBridge(options =>
+{
+    options.EnableDiagnosticEndpoints = builder.Environment.IsDevelopment();
+    // ...
+});
+```
+
+### Logging Categories
+
+Configure logging for troubleshooting:
+
+```json
+{
+  "Logging": {
+    "LogLevel": {
+      "StellaOps.Microservice.AspNetCore.Discovery": "Debug",
+      "StellaOps.Microservice.AspNetCore.Authorization": "Debug",
+      "StellaOps.Microservice.AspNetCore.Dispatch": "Information"
+    }
+  }
+}
+```
+
+---
+
 ## Testing Strategy
 
 ### Unit Tests