stela ops usage fixes roles propagation and timoeut, one account to support multi tenants, migrations consolidation, search to support documentation, doctor and open api vector db search

docs/modules/router/webservice-integration-guide.md

@@ -48,6 +48,94 @@ builder.Services.TryAddStellaRouter(
     routerOptions: options.Router);
 ```
 
+#### Optional: generic microservice transport registration
+
+For services that should auto-register transport clients from configuration, use:
+
+```csharp
+builder.Services.AddRouterMicroservice(
+    builder.Configuration,
+    serviceName: "my-service-name",
+    version: typeof(Program).Assembly.GetName().Version?.ToString() ?? "1.0.0",
+    routerOptionsSection: "MyService:Router");
+```
+
+`AddRouterMicroservice(...)` keeps `TryAddStellaRouter(...)` behavior and registers transport clients through `RouterTransportPluginLoader` based on configured gateway transport types (`InMemory`, `Tcp`, `Certificate`/`tls`, `Udp`, `RabbitMq`, `Messaging`).  
+The `StellaOps.Router.AspNet` library does not hard-reference transport assemblies; transports are activated from plugin DLLs and environment/config values.
+
+For Valkey messaging mode, configure:
+
+```yaml
+myservice:
+  router:
+    enabled: true
+    region: "local"
+    transportPlugins:
+      directory: "plugins/router/transports"
+      searchPattern: "StellaOps.Router.Transport.*.dll"
+    gateways:
+      - host: "router.stella-ops.local"
+        port: 9100
+        transportType: "Messaging"
+    messaging:
+      transport: "valkey"
+      pluginDirectory: "plugins/messaging"
+      searchPattern: "StellaOps.Messaging.Transport.*.dll"
+      requestQueueTemplate: "router:requests:{service}"
+      responseQueueName: "router:responses"
+      consumerGroup: "myservice"
+      requestTimeout: "30s"
+      leaseDuration: "5m"
+      batchSize: 10
+      heartbeatInterval: "10s"
+      valkey:
+        connectionString: "cache.stella-ops.local:6379"
+```
+
+### 2.2 Gateway trust mode and identity envelope verification
+
+Service-side Router bridge can enforce gateway-issued identity semantics:
+
+```yaml
+myservice:
+  router:
+    authorizationTrustMode: "GatewayEnforced" # ServiceEnforced | Hybrid | GatewayEnforced
+    identityEnvelopeSigningKey: "${ROUTER_IDENTITY_SIGNING_KEY}"
+    identityEnvelopeClockSkewSeconds: 30
+```
+
+- `ServiceEnforced`: service-local checks remain primary.
+- `Hybrid`: prefer signed envelope; fallback to legacy headers.
+- `GatewayEnforced`: fail closed when envelope is missing/invalid.
+
+### 2.3 Timeout precedence
+
+Gateway dispatch timeout is now resolved with explicit precedence:
+
+1. Endpoint timeout (including endpoint override/service default published by service).
+2. Route default timeout (optional per gateway route via `defaultTimeout`).
+3. Gateway routing default timeout (`Gateway:Routing:DefaultTimeout`).
+4. Global gateway cap (`Gateway:Routing:GlobalTimeoutCap`).
+
+Route-level timeout example:
+
+```yaml
+gateway:
+  routing:
+    defaultTimeout: "30s"
+    globalTimeoutCap: "120s"
+  routes:
+    - type: Microservice
+      path: "/api/v1/timeline"
+      translatesTo: "http://timelineindexer.stella-ops.local/api/v1/timeline"
+      defaultTimeout: "15s"
+```
+
+### 2.1 Gateway SPA deep-link handling with microservice routes
+
+When gateway route prefixes overlap with UI routes (for example `/policy`), browser navigations must still resolve to the SPA shell.  
+Gateway `RouteDispatchMiddleware` now serves the configured static SPA fallback route for browser document requests on both `ReverseProxy` and `Microservice` route types. API prefixes (`/api`, `/v1`) are explicitly excluded from this fallback and continue to dispatch to backend services.
+
 ### 3. Enable Middleware
 
 After `UseAuthorization()`, add: