feat: add preprod observability foundation

README.md

@@ -82,6 +82,37 @@ The deploy workflow writes the remote `.env` file and syncs `deploy/compose.yml`
 before running the server deploy script.
 Use the raw Resend API key value for `RESEND_API_KEY`, without a `Bearer ` prefix.
 
+## Preprod Observability
+
+The optional observability overlay runs a self-hosted Grafana stack for preproduction:
+
+- Grafana `13.0.1`: dashboards
+- Prometheus `v3.11.3`: metrics and local alert rules
+- Loki `3.7.1`: Docker/container logs
+- Tempo `2.10.3`: traces
+- Grafana Alloy `v1.16.0`: OTLP receiver and Docker log collector
+
+Start the app with observability:
+
+```bash
+docker compose -f deploy/compose.yml -f deploy/observability/compose.observability.yml up -d
+```
+
+Grafana is exposed at:
+
+```txt
+http://127.0.0.1:3000
+```
+
+Default credentials are `admin` / `admin` unless `GRAFANA_ADMIN_USER` and
+`GRAFANA_ADMIN_PASSWORD` are set. Set `GRAFANA_HTTP_BIND=0.0.0.0` only when the
+preprod network boundary is trusted or protected by a reverse proxy/VPN.
+
+Set a non-default `GRAFANA_ADMIN_PASSWORD` before exposing Grafana outside the
+host. Prometheus alert rules are provisioned under
+`deploy/observability/prometheus/rules/`; notification delivery is intentionally
+left to the preprod operations environment.
+
 ## Solution
 
 ```bash