README: PWA deploy lessons (stale COPY layer, icon cache-busting, maskable safe zone, Firefox crossorigin, theme bars)

README.md

@@ -336,3 +336,23 @@ equal the number of members who have logged in to the sandbox.
   `mcp/server.py`, `mcp/image_server.py` md5s match the live volume; overlay
   image `registry.inference.coop/co-op/librechat-custom:20261019-fc9b11e` is
   deployed (container asset md5s match this repo).
+
+## PWA lessons (2026-10-22 — icon/band debugging)
+
+- **Builder COPY layers can be stale**: after editing any asset, build with
+  `--no-cache` and VERIFY the served file's md5 against the repo before
+  reporting success. (The 20261022-df55d7f build shipped a stale maskable icon
+  this way — the repo was right, the image wasn't.)
+- **PWA icon URLs must carry a per-build `?v=`**: they are served with
+  `max-age=172800`, and remove/re-add of the PWA does not clear the phone's
+  HTTP cache — launchers keep rendering the previous build's icon bytes.
+  patch_index.py injects the query into every manifest icon src per build.
+- **Maskable icons**: logo must sit inside the safe zone — ~66% of the canvas
+  on a solid brand background. Full-bleed logos get cropped ("zoomed in").
+- **Firefox Android**: `crossorigin="use-credentials"` on the manifest link
+  breaks icon resolution (blank launcher icon) — patch_index.py strips it.
+- **Theme bars**: the manifest `theme_color` is one static value; Chromium's
+  nav bar and all Firefox bars use it even when the meta says otherwise. The
+  durable fix is `viewport-fit=cover` + standalone-mode safe-area padding
+  (custom.css) so the bands show the theme-correct page background; custom2.js
+  additionally syncs one meta `theme-color` to the app's resolved theme.