work work hard work

docs/modules/router/README.md

@@ -12,6 +12,7 @@ StellaOps already has HTTP-based services. The Router exists because:
 4. **Health-aware Routing**: Automatic failover based on heartbeat and latency
 5. **Claims-based Auth**: Unified authorization via Authority integration
 6. **Transport Flexibility**: UDP for small payloads, TCP/TLS for streams, RabbitMQ for queuing
+7. **Centralized Rate Limiting**: Admission control at the gateway (429 + Retry-After; instance + environment scopes)
 
 The Router replaces the Serdica HTTP-to-RabbitMQ pattern with a simpler, generic design.
 
@@ -84,6 +85,7 @@ StellaOps.Router.slnx
 | [schema-validation.md](schema-validation.md) | JSON Schema validation feature |
 | [openapi-aggregation.md](openapi-aggregation.md) | OpenAPI document generation |
 | [migration-guide.md](migration-guide.md) | WebService to Microservice migration |
+| [rate-limiting.md](rate-limiting.md) | Centralized router rate limiting |
 
 ## Quick Start
 

docs/modules/router/architecture.md

@@ -508,6 +508,7 @@ OpenApi:
 | Unauthorized | 401 Unauthorized |
 | Missing claims | 403 Forbidden |
 | Validation error | 422 Unprocessable Entity |
+| Rate limit exceeded | 429 Too Many Requests |
 | Internal error | 500 Internal Server Error |
 
 ---
@@ -517,3 +518,4 @@ OpenApi:
 - [schema-validation.md](schema-validation.md) - JSON Schema validation
 - [openapi-aggregation.md](openapi-aggregation.md) - OpenAPI document generation
 - [migration-guide.md](migration-guide.md) - WebService to Microservice migration
+- [rate-limiting.md](rate-limiting.md) - Centralized Router rate limiting

docs/modules/router/rate-limiting.md

@@ -0,0 +1,39 @@
+# Router · Rate Limiting
+
+This page is the module-level dossier for centralized rate limiting in the Router gateway (`StellaOps.Router.Gateway`).
+
+## What it is
+- A **gateway responsibility** that applies policy and protects both the Router process and upstream microservices.
+- Configurable by environment, microservice, and (for environment scope) by route.
+- Deterministic outputs and bounded metric cardinality by default.
+
+## How it works
+
+### Scopes
+- **for_instance**: in-memory sliding window counters (fast path).
+- **for_environment**: Valkey-backed fixed windows (distributed coordination).
+
+### Inheritance
+- Environment defaults → microservice override → route override.
+- Replacement semantics: a more-specific `rules` set replaces the parent rules.
+
+### Rule stacking
+- Multiple rules on a target are evaluated with AND logic.
+- Denials return the most restrictive `Retry-After` across violated rules.
+
+## Operational posture
+- Valkey failures are fail-open (availability over strict enforcement).
+- Activation gate reduces Valkey load at low traffic.
+- Circuit breaker prevents cascading latency when Valkey is degraded.
+
+## Migration notes (avoid double-limiting)
+- Prefer centralized enforcement at the Router; remove service-level HTTP limiters after Router limits are validated.
+- Roll out in phases (high limits → soft limits → production limits).
+- If a microservice must keep internal protection (e.g., expensive job submission), ensure it is semantically distinct from HTTP admission control and does not produce conflicting client UX.
+
+## Documents
+- Configuration guide: `docs/router/rate-limiting.md`
+- Per-route guide: `docs/router/rate-limiting-routes.md`
+- Ops runbook: `docs/operations/router-rate-limiting.md`
+- Testing: `tests/StellaOps.Router.Gateway.Tests/` and `tests/load/router-rate-limiting-load-test.js`
+