diff --git a/.env.example b/.env.example
index 7593d997..08d9154a 100644
--- a/.env.example
+++ b/.env.example
@@ -39,6 +39,12 @@ PORT_PROMETHEUS=9090
 # Grafana admin password — change this before exposing Grafana beyond localhost
 GRAFANA_ADMIN_PASSWORD=changeme
 
+# Password for the read-only grafana_reader PostgreSQL role used by the PO
+# Overview dashboard. Consumed by Flyway V68 (to set the role's password) and
+# by Grafana's PostgreSQL datasource (to connect). REQUIRED in production —
+# generate with: openssl rand -hex 32
+GRAFANA_DB_PASSWORD=changeme-generate-with-openssl-rand-hex-32
+
 # GlitchTip domain — production: use https://glitchtip.archiv.raddatz.cloud (must match Caddy vhost)
 GLITCHTIP_DOMAIN=http://localhost:3002
 
diff --git a/infra/observability/obs.env b/infra/observability/obs.env
index 1c46a8fe..a0632f5b 100644
--- a/infra/observability/obs.env
+++ b/infra/observability/obs.env
@@ -16,6 +16,11 @@ GLITCHTIP_DOMAIN=https://glitchtip.archiv.raddatz.cloud
 
 POSTGRES_USER=archiv
 
+# Note: GRAFANA_DB_PASSWORD is a secret and is injected by CI from
+# obs-secrets.env (see .env.example for the local-dev declaration).
+# It is consumed by both archive-backend (Flyway V68 placeholder) and
+# obs-grafana (PostgreSQL datasource).
+
 # PostgreSQL hostname for GlitchTip db-init and workers.
 # The actual value depends on the Compose project name — it is not a fixed string.
 # CI sets POSTGRES_HOST in obs-secrets.env per environment: