diff --git a/README.md b/README.md
index 94cde55..1ab914f 100644
--- a/README.md
+++ b/README.md
@@ -275,3 +275,40 @@ Adjust these constants and rerun `movmaker.py` to change the intro behavior with
 ## Notes
 
 This is an early version. The intended workflow is deliberately simple: dump files into one folder and run the script.
+
+## Web push notifications (MVLog web server)
+
+Movmaker itself does not send web push notifications. The MVLog web UI handles "Show" notifications server-side: when an authenticated admin enables the "Show" checkbox for a job the web server attempts to send a single web-push to all subscribers and records the send. This keeps the VAPID private key on the web host and centralizes notification logic.
+
+Files and behavior (deployed under the MVLog web root):
+
+- send_push.js — Node sender script (uses web-push). It reads subscriptions from stdin and accepts a push payload and a push config file path.
+- lib/send_push.php — server-side PHP helper used by new.php to call send_push.js and atomically update cache/push_notifications.json (the "shown" map).
+- api/enable_show.php — authenticated endpoint to toggle Show and trigger send (used by some integrations). It requires admin login.
+- new.php — the admin UI toggle now calls the server-side helper when Show is enabled (server-side send; non-fatal).
+- cache/push_subscriptions.json — stored subscriptions (array of subscription objects).
+- cache/push_notifications.json — recorded sends; the "shown" map prevents duplicate Show notifications.
+- push.json or /etc/mvlog/push.php — VAPID keys (private key must be kept secret and file permissions restricted).
+- log: /var/log/mvlog_notify.log — send attempts and errors are logged here.
+
+Deployment checklist
+
+1) Install Node.js and the web-push package under the web root (or system-wide):
+
+   npm install web-push --prefix /var/www/html/mvlog
+
+2) Place VAPID keys where the webserver can read them (recommended: /etc/mvlog/push.php or /var/www/html/mvlog/push.json) and set restrictive permissions (600 or 640, owner www-data). Do NOT commit private keys to git.
+
+3) Ensure /var/www/html/mvlog/cache exists and contains push_subscriptions.json and push_notifications.json (create {} if empty), owned by www-data and writable.
+
+4) Ensure /var/log/mvlog_notify.log is writable by the webserver user.
+
+5) The admin UI (new.php) requires login; enable Show from the admin UI to trigger a server-side send.
+
+Security notes
+
+- api/enable_show.php requires admin login; do not expose it publicly without strong auth.
+- Protect push private keys: file permission 600 and owned by web user. Do not store private keys in repository.
+- Consider adding CSRF protection, rate limiting, and periodic pruning of expired subscriptions (HTTP 410 responses).
+
+If you want deployment automation, alternative flows (worker-based sender or token-protected endpoint), or I should add a short admin checklist, tell me and I will update the docs.