diff --git a/README.md b/README.md
index b39b3ff..eb9685a 100644
--- a/README.md
+++ b/README.md
@@ -123,8 +123,12 @@ What the [upaas](https://git.eeqj.de/sneak/upaas) app for pixa needs:
       comma-separated; default none. Every image on a listed host is served to
       anyone without a signature, so list only hosts you control, where nobody
       else can put images.
-    - `PIXA_CACHE_MAX_BYTES`: disk cache limit in bytes; `0` disables it;
-      default 75% of (free space + what the cache holds)
+    - `PIXA_CACHE_MAX_BYTES`: disk cache limit in bytes; `0` disables it. Set
+      it: the volume is a directory on the host's filesystem, shared with the
+      host and every other app. The default is 75% of the sum of that
+      filesystem's free space and what the cache holds, and at least 500 MiB, so
+      the cache can grow to three quarters or more of the space they all have
+      left, and to all of it when that is 500 MiB or less.
     - the rest are in the table under Configuration below
 - **Health check:** the image's `HEALTHCHECK` requests
   `/.well-known/healthcheck.json`. upaas reads the container's health 60 seconds
diff --git a/TODO.md b/TODO.md
index 893924a..97ccf43 100644
--- a/TODO.md
+++ b/TODO.md
@@ -30,6 +30,13 @@ P2: security: per-origin rate limiting
 
 # Completed Steps
 
+- 2026-10-15 "Running under upaas" in `README.md` tells the operator to set
+  `PIXA_CACHE_MAX_BYTES` (closes #251): it listed the variable as optional, but
+  under upaas the volume is a directory on the host's filesystem. The default,
+  75% of the sum of that filesystem's free space and what the cache holds, and
+  at least 500 MiB, let one pixa take three quarters or more of the space the
+  host and every other app had left, and all of it when that was 500 MiB or
+  less. The section now says so. The default is unchanged.
 - 2026-10-15 the request metrics are labelled by route, not by path (closes
   #254): their `handler` label was each request's path, so every new path, a 404
   or an encrypted URL, added series to the Prometheus registry that were never