Add explicit rate limits and total connection limit

- Make RateLimit explicit in relay builder (500 subs, 60 events/min)
- Add NGIT_MAX_CONNECTIONS config option (default: 500)
- Update all 4 config locations (src, nix, docs, .env.example)
- Fix documentation error: filter limit 5000→500
- Document Phase 2 deferral decision (per-IP enforcement)

Addresses primary DoS vector (connection exhaustion) with minimal code.
Per-IP rate limiting deferred until abuse detected in production.

Related: issue ff38 (git endpoint throttling - separate concern)

1 files changed, 40 insertions, 0 deletions

diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index 8b49297..c3001d3 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -925,6 +925,46 @@ Event blacklist does **not** affect NIP-11 metadata:
 
 ---
 
+### Rate Limiting & DoS Protection
+
+#### `NGIT_MAX_CONNECTIONS`
+
+**Description:** Maximum total connections to the relay. Prevents connection exhaustion DoS attacks.  
+**Type:** Integer  
+**Default:** `500`  
+**Required:** No
+
+**Examples:**
+
+```bash
+# Default: 500 connections
+NGIT_MAX_CONNECTIONS=500
+
+# Higher limit for large public relay
+NGIT_MAX_CONNECTIONS=1000
+
+# Lower limit for private relay
+NGIT_MAX_CONNECTIONS=100
+```
+
+**Notes:**
+
+- Limits total concurrent WebSocket connections to the relay
+- Prevents connection exhaustion attacks
+- Works in conjunction with per-connection limits (500 subscriptions, 60 events/min)
+- When limit is reached, new connections are rejected
+- Existing connections continue to work normally
+
+**Related Limits:**
+
+Per-connection limits (built-in to relay-builder, not configurable):
+- Max subscriptions per connection: 500
+- Max events per minute per connection: 60
+- Max subscription ID length: 250 characters
+- Max results per filter: 500
+
+---
+
 ### Logging Configuration
 
 #### `RUST_LOG`