docs(web): clarify CDN caching, bump API stale-while-revalidate, and tidy README table

web/README.md

@@ -25,25 +25,26 @@ configured. Keep it that way; the CI `test` job builds with no database on purpo
 
 Connection config is read by `lib/db.ts`:
 
-| Variable | Required | Meaning |
-|---|---|---|
-| `BENCH_DB_HOST` | yes | Postgres host. |
-| `BENCH_DB_NAME` | yes | Database name. |
-| `BENCH_DB_USER` | yes | Role to connect as. |
-| `BENCH_DB_PORT` | no (5432) | Port. |
-| `BENCH_DB_PASSWORD` | no | Static password. When unset, each new connection authenticates with a freshly minted RDS IAM token instead. |
-| `BENCH_DB_REGION` | for IAM | AWS region for the RDS IAM signer; required when no password is set. IAM token signing also needs AWS credentials in the runtime environment. |
-| `BENCH_DB_SSL` | no (`verify-full`) | `verify-full` validates the certificate chain and hostname; `disable` is for local non-TLS containers only. Any other value fails loudly. |
-| `BENCH_DB_CA` | prod | PEM contents of the Amazon RDS CA bundle; Node's trust store does not include the RDS roots, so `verify-full` against RDS fails without it. |
-| `BENCH_DB_POOL_MAX` | no (8) | Max pool connections per serverless instance; the per-render summary fan-out (`SUMMARY_CONCURRENCY`) is sized to this default. |
+| Variable            | Required           | Meaning                                                                                                                                       |
+| ------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BENCH_DB_HOST`     | yes                | Postgres host.                                                                                                                                |
+| `BENCH_DB_NAME`     | yes                | Database name.                                                                                                                                |
+| `BENCH_DB_USER`     | yes                | Role to connect as.                                                                                                                           |
+| `BENCH_DB_PORT`     | no (5432)          | Port.                                                                                                                                         |
+| `BENCH_DB_PASSWORD` | no                 | Static password. When unset, each new connection authenticates with a freshly minted RDS IAM token instead.                                   |
+| `BENCH_DB_REGION`   | for IAM            | AWS region for the RDS IAM signer; required when no password is set. IAM token signing also needs AWS credentials in the runtime environment. |
+| `BENCH_DB_SSL`      | no (`verify-full`) | `verify-full` validates the certificate chain and hostname; `disable` is for local non-TLS containers only. Any other value fails loudly.     |
+| `BENCH_DB_CA`       | prod               | PEM contents of the Amazon RDS CA bundle; Node's trust store does not include the RDS roots, so `verify-full` against RDS fails without it.   |
+| `BENCH_DB_POOL_MAX` | no (8)             | Max pool connections per serverless instance; the per-render summary fan-out (`SUMMARY_CONCURRENCY`) is sized to this default.                |
 
 ## CDN caching
 
-The read paths serve traffic through Vercel's CDN with a five-minute freshness window, matching
-the v2 site's S3 refresh cadence:
+The read paths serve traffic through Vercel's CDN with a five-minute fresh window, matching
+the v2 site's S3 refresh cadence, plus bounded stale-while-revalidate windows for low-traffic
+warmth:
 
 - The data routes (`/api/groups`, `/api/group/*`, `/api/chart/*`) set
-  `Cache-Control: public, s-maxage=300, stale-while-revalidate=300` on success responses
+  `Cache-Control: public, s-maxage=300, stale-while-revalidate=3600` on success responses
   (`lib/cache.ts`); error responses omit the header so they are never CDN-cached. `/api/health`
   is deliberately uncached so the liveness probe always reflects the live database.
 - The HTML pages (`/` and `/chart/:slug`) cannot set response headers from a server component,
@@ -53,15 +54,18 @@ the v2 site's S3 refresh cadence:
   precedence, so the CDN caches the rendered pages while browsers still revalidate every load.
 
 Verify on a live deployment with `curl -sI <url> | grep -i x-vercel-cache` (expect `MISS` then
-`HIT` within five minutes). The deploy workflow runs this probe automatically after each deploy.
+`HIT` within the five-minute fresh window). The deploy workflow runs this probe automatically after
+each deploy.
 When deployment protection returns 401/403 on a deployment URL the probe skips with a notice;
 production avoids that blind spot automatically once `BENCHMARKS_WEB_PROD_URL` is set (the probe
 then targets the public domain, where a 401/403 fails the run instead), so the manual check is
 only needed for protected previews and for production while the var is unset. One deliberate
 divergence from the API routes: the `vercel.json` header rules apply to every response status,
-so an unknown `/chart/:slug` 404 can be CDN-cached for up to five minutes, which stays within
-the site's five-minute staleness budget (transient 5xx responses are believed not CDN-cacheable
-by Vercel; if one ever were, the same five-minute budget would bound it).
+so an unknown `/chart/:slug` 404 follows the HTML page rule: five minutes fresh and then eligible
+for Vercel's one-day stale-while-revalidate window. That is acceptable for opaque, never-linked
+malformed/unknown chart URLs, while real chart pages refresh on the same five-minute fresh cadence
+as the landing page (transient 5xx responses are believed not CDN-cacheable by Vercel; if one ever
+were, the same HTML page rule would bound it).
 
 ## Deploys