docs(skill): ask for a version rollback before reproducing or reverting

Follow-up to #3026/#3028. The sub_filter was blamed for a download regression
and reverted; the reporter's own rollback to 1.5.3, which predates the filter,
showed identical behaviour and the revert was closed unmerged. Records the
sequencing lesson, the ruled-out layers, and the registry-layer rig.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.claude/skills/hassio-addon-workflow/references/evidence.md

@@ -58,3 +58,64 @@ Once the rebuilt add-on is running, re-run the measurement that motivated the wo
 cannot be self-verified — a service that reads its environment only at start makes an env-var fix
 unproven until the add-on restarts, which needs the user or `ha-cli` with their agreement. If you
 cannot restart, the change is **Assumed**, not Verified, and must be reported that way.
+
+## When your change is blamed for a regression, ask for a version rollback first
+
+PR #3026 added an nginx `sub_filter` to the `filebrowser_quantum` ingress vhost. Right after it
+merged the user reported Download had broken — the file opened inline instead of downloading — and
+confirmed it still worked on the add-on's direct port, which serves `direct.conf` and carries no
+`sub_filter`. That made the filter the only ingress-side change in the update, so PR #3028 reverted
+it. Meanwhile every measurement said the filter was not involved:
+
+- the shipped bundle's Download action builds an `<a href>` and clicks it, and never calls
+  `window.open`, which is all the injected shim overrides;
+- the shim's own predicate, evaluated live in the running app, returned false for the download
+  URL, the `inline=true` raw URL and the public-share download URL;
+- the download response through the vhost was **byte-identical** with and without the `sub_filter`
+  (`Content-Disposition: attachment` intact, `Content-Length` unchanged), for `text/plain` and for
+  the `text/html` case the filter actually scans;
+- upstream's frontend download code is unchanged from v1.5.0-stable to v1.5.4-stable; Supervisor's
+  ingress proxy forwards `Content-Disposition` (`_response_header` drops only `Transfer-Encoding`,
+  `Content-Length`, `Content-Type`, `Content-Encoding`); and the ingress panel's iframe carries no
+  `sandbox` attribute, so downloads are not sandbox-blocked.
+
+The measurements were right. The user then rolled their add-on back to **1.5.3**, which predates the
+filter, saw the identical behaviour, and the revert was closed unmerged.
+
+**The lesson is about sequencing, not about who was right.** "Works on the old version, breaks on the
+new one" is the only cheap experiment that actually isolates a shipped change, and only the reporter
+can run it. Ask for it *first* — before building a reproduction, before opening a revert. It costs
+them one add-on downgrade and it either confirms the regression or, as here, redirects the whole
+investigation. A revert is the fallback for when they cannot roll back, not the opening move.
+
+Two corollaries:
+
+- **Do not let a clean local reproduction settle it either.** Being unable to reproduce is not
+  evidence of absence, and the reporter watching it fail on their own instance outranks it. Both
+  sides of that needed the rollback to resolve.
+- **`build_from: <image>:latest` means every merge ships an upstream version bump too**, so "it
+  broke when your PR landed" never implicates the diff on its own. Record which upstream version
+  each add-on image was built from — the registry config blob's `created` timestamp, the resolved
+  manifest digest, and the binary's version string. Here: add-on 1.5.3 was built 2026-08-28 23:29
+  UTC from upstream v1.5.3-stable, 1.5.3.1 on 2026-08-30 06:00 UTC from v1.5.4-stable
+  (`sha256:e549e1a9…`). If you do use a revert as the experiment, both builds must resolve the same
+  upstream digest or it proves nothing:
+
+  ```bash
+  T=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:<repo>:pull" | jq -r .token)
+  curl -s -H "Authorization: Bearer $T" \
+       -H "Accept: application/vnd.oci.image.index.v1+json" \
+       "https://registry-1.docker.io/v2/<repo>/manifests/latest" \
+    | jq -r '.manifests[] | select(.platform.architecture=="amd64" and .platform.os=="linux") | .digest'
+  ```
+
+Worth building anyway, because it is reusable and needs no dockerd: a reproduction rig made **out of
+the published image's own layers**. Pull the manifest and blobs from the registry with `curl` + `jq`,
+untar them in order, then run the extracted binary through the image's own musl loader
+(`root/lib/ld-musl-x86_64.so.1 ./filebrowser`) with the real `http/dist` next to it. Put the add-on's
+rendered `ingress.conf` in front of it, and a second nginx in front of that to strip the
+`/api/hassio_ingress/<token>` prefix the way Supervisor does. That gets the real frontend, the real
+backend and the real vhost under a browser — everything except Supervisor itself. Plain `tar` does
+not interpret whiteouts, so a file a later layer deletes (`.wh.<name>`) or a directory it marks
+opaque (`.wh..wh..opq`) survives into the reconstructed rootfs; check with
+`tar tzf <layer> | grep '\.wh\.'` and reach for an OCI-aware unpacker if any turn up.

.github/stargazer_countries.csv

@@ -273,6 +273,7 @@ Gajalshankar,India,
 Gangol,,2026-08-10
 Garak1980,,2026-08-10
 GaryOG,,2026-08-10
+GentryChe,,2026-08-30
 Germaenace,,2026-08-10
 Getrio,Italy,
 Ghost-Sam1222,,2026-08-10
@@ -385,6 +386,7 @@ JosephBlock,United States,
 Julian1701,,2026-08-10
 JulienFloris,Netherlands,
 JuraLadanov,,2026-08-10
+Jutsch,,2026-08-30
 K0stIa,,2026-08-10
 KRC604,,2026-08-10
 KairuByte,,2026-08-10
@@ -441,6 +443,7 @@ Lizzardis,,2026-08-10
 LoginByCall,,2026-08-10
 Lolekpolek,,2026-08-10
 LonelySoul7X,,2026-08-10
+Loong-He,China,2026-08-30
 Lorsel,Italy,
 Luca2165801154,,2026-08-10
 Lucius-Waverly,,2026-08-16
@@ -990,6 +993,7 @@ berkovich98,,2026-08-10
 bertrand-f,,2026-08-10
 bes-r,Netherlands,
 bestnub,Germany,
+betechyou,,2026-08-30
 beyercenter,,2026-08-10
 bezigebever,,2026-08-10
 bggsolar,Germany,
@@ -1225,6 +1229,7 @@ denisgolius,Ukraine,
 dennisjonda,Germany,
 dennisvandalen,Netherlands,
 denvernbd,Russian Federation,2026-08-10
+der-berni,Germany,2026-08-30
 derailius,,2026-08-10
 dethpickle,United States,
 dev4jam,Australia,
@@ -1522,6 +1527,7 @@ hreikin,United Kingdom,
 hsiguy,,2026-08-10
 huangyixinv,,2026-08-10
 hubikj,,2026-08-10
+hufforguk,,2026-08-30
 hugobloem,United Kingdom,
 hujiayi0126,,2026-08-10
 hunterlong,United States,
@@ -1661,6 +1667,7 @@ joshcliffejones,United Kingdom,
 joshmeads,Canada,
 josiah-eichelman,,2026-08-10
 jpaulomt,,
+jpeisach,United States,2026-08-30
 jpmaldonado,,2026-08-10
 jpoll962,,2026-08-10
 jpombas,Portugal,
@@ -1831,6 +1838,7 @@ mProwler,United States,
 mStrangers,,2026-08-10
 mabt,,2026-08-10
 macedobernardo,,2026-08-10
+machineGnu,,2026-08-30
 madjetey,,2026-08-10
 maggle-swim,,2026-08-10
 malachitgruen,Germany,
@@ -1840,6 +1848,7 @@ manu7691,United States,
 manugratx,,2026-08-10
 mapeje,Sweden,
 maphouse,Canada,
+marat-365,,2026-08-30
 maratbakirov,,2026-08-10
 marcetad,,2026-08-10
 marcjay,United Kingdom,
@@ -1849,6 +1858,7 @@ marcschraepler,Austria,
 marcusrbrown,,2026-08-10
 mareklab,,2026-08-10
 marevers,Germany,
+marialaranjo,,2026-08-30
 marian-paun,Romania,
 mariusvslprts,Germany,
 mark-219,United States,2026-08-16
@@ -2173,6 +2183,7 @@ pwitte,,2026-08-10
 pxshh,,2026-08-10
 pynbbz,,2026-08-10
 pyrech,France,
+pysj,,2026-08-30
 pziezio,Poland,
 pzkpfw6,,2026-08-10
 qadk,,2026-08-10
@@ -2196,6 +2207,7 @@ rascasseuk,,2026-08-10
 raul811,,2026-08-10
 raulpetruta,Romania,
 rawpie2,,2026-08-10
+raymand211092,Cuba,2026-08-30
 raytedjaja,,2026-08-10
 rbalaev,,2026-08-10
 rbaron,,2026-08-10
@@ -2211,6 +2223,7 @@ reggiano,,2026-08-10
 reid,United States,
 reinvanhaaren,Netherlands,
 remb0,Netherlands,
+renatoptr,,2026-08-30
 renejr63,,2026-08-10
 resomi,,2026-08-10
 retpolanne,Brazil,

filebrowser_quantum/CHANGELOG.md

@@ -1,4 +1,15 @@
  
+## 1.5.3.1 (2026-08-29)
+- Fix "open parent directory" in Tools -> File Size Analyzer under Home
+  Assistant ingress. FileBrowser opened the parent folder in a new tab, which
+  lands on the raw ingress URL with no Home Assistant frontend around it to
+  keep the ingress session alive, so the new tab answered 401 instead of
+  showing the folder. The ingress vhost now turns that popup into a navigation
+  of the panel itself. The same fix covers the other tool views and the "go to
+  item" action on search results, which open a new tab the same way. Download
+  and preview popups, links pointing out of the add-on, and direct access on
+  port 8071 are unchanged.
+ 
 ## 1.5.3 (2026-08-29)
 - Update to latest version from gtsteffaniak/filebrowser (changelog : https://github.com/gtsteffaniak/filebrowser/releases)
  

filebrowser_quantum/config.yaml

@@ -118,4 +118,4 @@ schema:
 slug: filebrowser_quantum
 udev: true
 url: https://github.com/alexbelgium/hassio-addons
-version: "1.5.3"
+version: "1.5.3.1"

filebrowser_quantum/rootfs/etc/nginx/servers/ingress.conf

@@ -3,7 +3,7 @@ server {
 
     include /etc/nginx/includes/server_params.conf;
     include /etc/nginx/includes/proxy_params.conf;
-    
+
     client_max_body_size 0;
 
    location / {
@@ -12,6 +12,35 @@ server {
        proxy_send_timeout 30m;
        proxy_read_timeout 30m;
        proxy_pass         %%protocol%%://backend%%subpath%%;
+
+       # Tools -> File Size Analyzer (and the other tool views) open a result's
+       # parent folder with window.open(<absolute url>, '_blank'), because
+       # goToItem() takes its newTab argument from the context menu's
+       # showLimitedOptions flag, which those views always set. Behind ingress
+       # that popup lands on the raw /api/hassio_ingress/<token>/ url with no
+       # Home Assistant frontend around it to keep the ingress session alive,
+       # so the new tab answers 401 instead of showing the folder. Turn that
+       # popup into a navigation of the panel itself.
+       #
+       # The context menu's "go to item" action, which search results and the
+       # tool views also offer, hardcodes the same new tab and is fixed too.
+       #
+       # Scoped to the two prefixes goToItem() builds, "files/" and
+       # "public/share/", so the window.open calls that download or preview a
+       # file (they go to api/resources/download) keep their own tab: sending
+       # an inline raw file to location.assign would replace the whole app.
+       # A link out of the add-on keeps its own tab as well, unless a user
+       # points a sidebar link (or a link inside a file open in the editor) at
+       # this same instance's files/ or public/share/ route, which then also
+       # opens in the panel. Same shape as the komga add-on's ingress filter.
+       #
+       # Injected into the page's existing nonce-carrying inline script rather
+       # than next to <div id="app">: FileBrowser sends
+       # script-src 'self' 'nonce-<random>', so a standalone inline <script>
+       # would be blocked. If upstream ever drops that
+       # window.__pwaDeferredPrompt line the filter simply stops matching and
+       # the popup behaviour returns, which is the pre-fix state.
+       sub_filter "window.__pwaDeferredPrompt = null;" "window.__pwaDeferredPrompt = null;(function(){var o=window.open;window.open=function(u,n,f){try{var b=(window.globalVars||{}).baseURL;if(u&&n==='_blank'&&!f&&b){if(b.slice(-1)!=='/')b+='/';var t=new URL(u,location.href);if((t.protocol==='http:'||t.protocol==='https:')&&t.origin===location.origin&&(t.pathname.indexOf(b+'files/')===0||t.pathname.indexOf(b+'public/share/')===0)){location.assign(t.href);return window}}}catch(e){}return o.apply(window,arguments)}})();";
   }
 
 }