feat: harden gateway with policy engine, secure tools, and governance docs

docs/observability.md

@@ -0,0 +1,28 @@
+# Observability
+
+## Logging
+
+- Structured JSON logs.
+- Request correlation via `X-Request-ID`.
+- Security events and policy denials are audit logged.
+
+## Metrics
+
+Prometheus-compatible endpoint: `GET /metrics`.
+
+Current metrics:
+- `aegis_http_requests_total{method,path,status}`
+- `aegis_tool_calls_total{tool,status}`
+- `aegis_tool_duration_seconds_sum{tool}`
+- `aegis_tool_duration_seconds_count{tool}`
+
+## Tracing and Correlation
+
+- Request IDs propagate in response header (`X-Request-ID`).
+- Tool-level correlation IDs included in MCP responses.
+
+## Operational Guidance
+
+- Alert on spikes in 401/403/429 rates.
+- Alert on repeated `access_denied` and auth-rate-limit events.
+- Track tool latency trends for incident triage.