docs(#2781): document proxy auth PWA update caveat

[rodboev]

Thinking Path

• The issue stopped being a runtime bug once the reporter confirmed the blank-screen loop disappears with WebUI's own password and no Caddy basic auth.
• static/sw.js already keeps service-worker updates, login assets, API/health, and navigations on live network paths, so the remaining gap is operator guidance for reverse-proxy basic-auth deployments rather than a WebUI code change.
• The fix adds that guidance where operators will actually see it: the README auth notes, onboarding's password step, and troubleshooting with a concrete recovery flow.

What Changed

• README.md: add a short authentication caveat for installed PWAs behind reverse-proxy basic auth, with a pointer to troubleshooting.
• docs/onboarding.md: expand the Password step so reverse-proxy deployments know when to prefer the built-in WebUI password and why.
• docs/troubleshooting.md: add a blank-screen-after-update diagnostic flow covering proxy 401 checks, practical mitigations, and site-scoped cleanup.

Why It Matters

Operators keep reverse-proxy support, but they get a clear warning about the one auth layering that can strand an installed PWA on a blank shell after updates. That turns a confusing "clear everything" failure into a specific config choice and a recoverable cleanup path.

Verification

• rg -n "reverse proxy|basic auth|WebUI password|PWA|blank screen|site data" README.md docs/onboarding.md docs/troubleshooting.md
• git diff --check HEAD^ HEAD
• Manual: review the updated README.md, docs/onboarding.md, and docs/troubleshooting.md sections together to confirm they preserve reverse-proxy support, recommend the built-in WebUI password for installed PWAs behind proxy basic auth, and include site-scoped recovery steps for an already blank shell.

Upstream

Closes #2781.

Model Used

GPT 5.5 via Codex CLI

[greptile-apps]

Greptile Summary

This PR adds operator guidance for the known interaction between reverse-proxy HTTP basic auth and installed PWAs — specifically that proxy 401 responses can interrupt service-worker shell-update fetches and leave the installed app on a blank screen after a WebUI update. No code changes are included; the fix is purely documentation across three files.

• README.md: New bullet in the Authentication section flags the proxy-auth/PWA caveat and points to the troubleshooting doc.
• docs/onboarding.md: Password step expanded with a recommendation to prefer WebUI's built-in password for PWA deployments and a note on scoping proxy auth if kept.
• docs/troubleshooting.md: New entry following the established Symptom/Why/Diagnostic/Fix/When-to-file-a-bug structure, covering 401 log checks, the temporary-removal confirmation test, site-data cleanup for an already-blank shell, and a clear bar for filing a WebUI bug.

Confidence Score: 5/5

Documentation-only change; no runtime code is touched and all three files contain accurate, actionable guidance.

All three files change only prose. The technical claims (proxy 401 blocking sw.js/manifest fetches, site-data cleanup as recovery) are correct, the new troubleshooting section matches the established format in the file, and there are no broken cross-references. The one suggestion is a non-clickable path in README.md that could be a markdown anchor link.

No files require special attention; the only note is the bare backtick path in README.md that could be a clickable anchor link.

Important Files Changed

Filename	Overview
README.md	Adds a single bullet in the Authentication section warning about proxy basic auth + installed PWA interaction; pointer to troubleshooting uses a bare backtick path instead of a markdown hyperlink.
docs/onboarding.md	Expands the Password step with a paragraph recommending WebUI's built-in password over proxy basic auth for installed PWAs; technically accurate and follows the existing prose style.
docs/troubleshooting.md	Adds a new 'Installed PWA opens to a blank screen after an update' section with Symptom/Why/Diagnostic/Fix/When-to-file-a-bug structure matching the existing file conventions; content is accurate and actionable.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Installed PWA opens after WebUI update] --> B{Blank screen?}
    B -- No --> Z[No action needed]
    B -- Yes --> C[Open same URL in normal browser tab]
    C --> D{Loads in tab?}
    D -- No --> E[Broader WebUI issue — file bug]
    D -- Yes --> F[Check proxy logs for 401 on sw.js / manifest.json / static/*]
    F --> G{401s found?}
    G -- No --> H[Blank screen without proxy auth? → file WebUI bug]
    G -- Yes --> I[Mitigation: use WebUI built-in password\nOR scope proxy auth to allow SW fetches]
    I --> J{Already blank shell?}
    J -- Yes --> K[Clear site data for Hermes origin\nThen reopen / reinstall PWA]
    J -- No --> L[Next update completes cleanly]
    K --> L

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Installed PWA opens after WebUI update] --> B{Blank screen?}
    B -- No --> Z[No action needed]
    B -- Yes --> C[Open same URL in normal browser tab]
    C --> D{Loads in tab?}
    D -- No --> E[Broader WebUI issue — file bug]
    D -- Yes --> F[Check proxy logs for 401 on sw.js / manifest.json / static/*]
    F --> G{401s found?}
    G -- No --> H[Blank screen without proxy auth? → file WebUI bug]
    G -- Yes --> I[Mitigation: use WebUI built-in password\nOR scope proxy auth to allow SW fetches]
    I --> J{Already blank shell?}
    J -- Yes --> K[Clear site data for Hermes origin\nThen reopen / reinstall PWA]
    J -- No --> L[Next update completes cleanly]
    K --> L

Loading

_{Reviews (1): Last reviewed commit: "docs(#2781): document proxy auth PWA upd..." | Re-trigger Greptile}

[nesquena-hermes]

🔬 Gate certification — GREEN ✅ (docs-only, light gate)

Certified head: sha:843e884e (clean rebase, branch gate-rebase/5673-proxy-auth-pwa-docs)

Docs-only (README.md + docs/onboarding.md + docs/troubleshooting.md, +21/-0, zero code) → light gate: content-accuracy + link/markdown sanity, no Codex/Fable/full-suite needed.

Check	Result
Docs-only (no code touched)	✅ 3 doc files, +21/-0
New troubleshooting section present + README cross-ref resolves	✅
Content technically accurate	✅ — correctly describes proxy basic-auth 401ing same-origin sw.js/manifest/static/* fetches during a service-worker shell update (the #2781 blank-screen-after-update cause), with sound diagnostic + fix (prefer WebUI password, or scope proxy auth to allow same-origin SW/shell fetches)
Markdown well-formed	✅ symptom/why/diagnostic/fix/when-to-file structure

Ready to merge — branch gate-rebase/5673-proxy-auth-pwa-docs. Accurate, useful docs for a real recurring PWA-behind-reverse-proxy gotcha (#2781). Credit @rodboev. concept 4/5, crit=3.

[nesquena-hermes]

Shipped in v0.51.901 (docs-only). Thanks @rodboev — the reverse-proxy basic-auth PWA caveat + blank-screen-after-update recovery steps are now in README, onboarding, and troubleshooting. Addresses #2781.