diff --git a/.env.example b/.env.example
index b00ece3a..de9f06a1 100644
--- a/.env.example
+++ b/.env.example
@@ -139,7 +139,11 @@ DEFT_AUDIT_BYPASS_TOKEN=
 METRICS_SCRAPE_TOKEN=
 
 # ── 7. Browser notifications (optional) ───────────────
-# Generate once with: pnpm --filter @deft/api exec web-push generate-vapid-keys
+# Generate once from a source checkout with:
+#   pnpm --filter @deft/api exec web-push generate-vapid-keys
+# or, on a Docker install without pnpm, inside the running app container:
+#   docker compose exec -w /app/apps/api deft node_modules/.bin/web-push generate-vapid-keys
+# VAPID_SUBJECT must start with mailto: or https://.
 # Keep this keypair stable; rotating it invalidates browser subscriptions.
 VAPID_PUBLIC_KEY=
 VAPID_PRIVATE_KEY=
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
index 154a3116..71d694d9 100644
--- a/docs/self-hosting.md
+++ b/docs/self-hosting.md
@@ -528,6 +528,7 @@ can supply its own AI independently of Deft's provider configuration.
 | `TRANSCRIPTION_OPENAI_API_KEY` | No | Key for that endpoint; empty falls back to `OPENAI_API_KEY`, and a keyless custom endpoint is called without one | `OPENAI_API_KEY` |
 | `R2_ENDPOINT` / `R2_ACCESS_KEY` / `R2_SECRET_KEY` / `R2_BUCKET` | No | Cloudflare R2 uploads | local uploads volume |
 | `METRICS_SCRAPE_TOKEN` | No | Bearer token for `/api/metrics` and `/health/queue`; unset disables detailed telemetry | none |
+| `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY` / `VAPID_SUBJECT` | No | Browser push notifications; set all three together, subject starting with `mailto:` or `https://`. Generate the keypair once (see `.env.example` section 7); rotating it invalidates existing browser subscriptions. Unset keeps the Inbox but disables Web Push | none |
 
 ### Opt-in Governed App Run keyrings