diff --git a/README.md b/README.md
index 1165224e5..25b799728 100644
--- a/README.md
+++ b/README.md
@@ -257,6 +257,7 @@ If an AI assistant is helping with install, reinstall, bootstrap, provider setup
 ### Authentication and security
 - Optional password auth -- off by default, zero friction for localhost
 - Enable via `HERMES_WEBUI_PASSWORD` env var or Settings panel
+- Installed PWAs work best with WebUI's own password. Reverse proxies are supported, but proxy basic auth can block the service-worker update fetches an installed app needs and leave it on a blank screen after an update; see `docs/troubleshooting.md` for recovery steps.
 - Optional passkeys/WebAuthn -- register from Settings -> System after signing in with a password; the login page only shows passkey sign-in after at least one passkey exists
 - After registering at least one passkey, Settings -> System can remove the password and keep passkey-only sign-in enabled. Password auth remains the bootstrap/recovery path until you choose to go passwordless; passkeys are same-origin and stored locally in the WebUI state directory
 - Optional native OIDC login for WebUI sessions -- configure `webui_oidc.issuer`, `client_id`, `allow_claim`, and `allow_values` in `config.yaml`, or set the matching `HERMES_WEBUI_OIDC_*` environment variables. OIDC stays disabled until all four are present, and startup prints a warning if the config is partial.
diff --git a/docs/onboarding.md b/docs/onboarding.md
index 710c7143c..57fe73540 100644
--- a/docs/onboarding.md
+++ b/docs/onboarding.md
@@ -168,6 +168,8 @@ Docker UID/GID and mount guidance in [Docker setup guide](docker.md).
 Password protection is optional for localhost-only installs. Enable it if you
 expose WebUI outside `127.0.0.1`, behind a reverse proxy, or on a LAN.
 
+For installed PWAs, prefer WebUI's built-in password over proxy basic auth. Reverse proxies are supported, but HTTP basic-auth challenges in front of the WebUI origin can interrupt the service-worker and shell-asset fetches the installed app relies on during updates. If you keep proxy auth, scope it so same-origin `sw.js`, manifest, and shell update requests can complete.
+
 The password is stored through the normal WebUI settings path and hashed
 server-side. You can change it later from Settings.
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 749547181..71d63d73a 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -159,6 +159,24 @@ turn in the exhausted session instead of being blocked with recovery guidance.
 
 ---
 
+## Installed PWA opens to a blank screen after an update
+
+**Symptom.** The installed PWA or home-screen app opens to a blank screen after a WebUI update, while the same URL often works again in a normal browser tab.
+
+**Why.** Reverse proxies are supported, but proxy basic auth can challenge the same-origin `sw.js`, manifest, or versioned `static/*` fetches the installed app needs while its service worker updates the shell.
+
+**Diagnostic.**
+
+1. Open the same WebUI URL in a regular browser tab and confirm whether it loads there.
+2. Check reverse-proxy logs for `401` responses on `/sw.js`, `/manifest.json`, or versioned `/static/*` assets during the update.
+3. Temporarily remove proxy basic auth and use WebUI's built-in password. If the blank screen stops after the next update, the proxy auth challenge was the trigger.
+
+**Fix.** Prefer WebUI's own password for installed PWAs. If you keep proxy basic auth, configure it so the same-origin service-worker and shell update fetches can complete. If the installed shell is already blank, clear site data for the Hermes origin, then reopen or reinstall the PWA after that site-scoped cleanup.
+
+**When to file a bug.** File a WebUI bug if the blank screen still reproduces without proxy basic auth, or after the proxy allows the same-origin service-worker and shell update fetches through.
+
+---
+
 ## Other troubleshooting
 
 This document grows over time. If a recurring failure mode isn't covered here yet, add it via PR. The format for each entry: **Symptom → Why → Diagnostic commands → Fix → When to file a bug**.