docs(deployment): drop immutable from nginx /uploads/ cache header

The nginx snippet in docs/deployment.md recommended
`Cache-Control: public, immutable` for `/uploads/`, which is wrong
for iManager's FileStorage layout.

FileStorage writes to `var/uploads/<itemId>/<fieldId>/<filename>`
keeping the user's original filename. Re-uploading a file under
the same name leaves the URL stable while the bytes change. With
`immutable` set, browsers serve the stale bytes for up to 30 days
(the `expires` window) and skip revalidation entirely.

Switch to `Cache-Control: public, must-revalidate` and add an
inline comment explaining the choice. The 30-day expires window
is kept; browsers now send `If-None-Match` on every hit and
nginx's built-in ETag answers 304 cheaply when the file is
unchanged, 200 with the new bytes when it changed.

The Caddy snippet in the same section was already correct (no
explicit Cache-Control, default revalidation), so it stays
untouched.

CHANGELOG entry under Unreleased / Documentation. No code or
behavior change.

This mirrors the same fix applied to Scriptor's docker/nginx.conf
in scriptor#fix/uploads-cache-immutable (the bug surfaced there
when re-uploading the same-named image kept showing the old one).

Author: bigin

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Documentation
+
+- **`docs/deployment.md`: nginx `/uploads/` block now recommends
+  `Cache-Control: public, must-revalidate` instead of
+  `public, immutable`.** iManager's FileStorage writes uploads to
+  `var/uploads/<itemId>/<fieldId>/<original-filename>`, so re-
+  uploading a file under the same name keeps the URL stable while
+  the bytes change. `immutable` would let browsers serve the old
+  bytes for up to 30 days; `must-revalidate` keeps the long
+  `expires 30d` but forces an If-None-Match check, which nginx's
+  built-in ETag answers cheaply with 304 when the file is
+  unchanged. Inline comment in the snippet explains the choice.
+  Caddy snippet was already correct (no explicit Cache-Control,
+  default revalidation). No code or behavior change.
+
 ## [2.2.1] — 2026-05-17
 
 Hotfix for the 2.2.0 upgrade path: `fts:rebuild` and `optimize` now

docs/deployment.md

@@ -153,11 +153,20 @@ server {
     index index.php;
 
     # Public uploads, served by nginx, no PHP.
+    # `must-revalidate` (not `immutable`): iManager's FileStorage
+    # writes to `var/uploads/<itemId>/<fieldId>/<original-filename>`,
+    # so re-uploading a file under the same name leaves the URL
+    # stable while the bytes change. `must-revalidate` makes the
+    # browser send an If-None-Match for every hit; nginx's built-in
+    # ETag answers 304 when the file on disk is unchanged (cheap,
+    # no transfer) or 200 with the new bytes when it changed.
+    # `immutable` would skip that revalidation and serve a stale
+    # asset for up to 30 days.
     location /uploads/ {
         alias /srv/app/var/uploads/;
         try_files $uri =404;
         expires 30d;
-        add_header Cache-Control "public, immutable";
+        add_header Cache-Control "public, must-revalidate";
     }
 
     # Defence-in-depth: never serve data/ or cache/.