diff --git a/.env.example b/.env.example
index 8ee920a1..be27dd59 100644
--- a/.env.example
+++ b/.env.example
@@ -6,10 +6,19 @@
 # Generate with: openssl rand -hex 32
 JWT_SECRET=your-secure-jwt-secret-key-here
 
-# PostgreSQL database password
+# PostgreSQL database password (the bootstrap superuser account; kept
+# for container initialization — the app itself connects as bookhoard_srv)
 # Generate with: openssl rand -hex 16
 DBPASS=your-secure-database-password-here
 
+# Runtime database role password (bookhoard_srv — the non-superuser
+# account the app connects as; subject to RLS). Required for the app to
+# start. On a fresh volume it is consumed by database/schema/z_rls_role.sh
+# during first initialization; on an existing volume, run that script once
+# (see its header) BEFORE starting the app with DATABASE_USER=bookhoard_srv.
+# Generate with: openssl rand -hex 16
+DBSRVPASS=your-secure-runtime-role-password-here
+
 # Networking: change a port if it conflicts on your host
 # Postgres port, host + container (e.g. another local DB already uses 5432)
 # DB_PORT=15432