The six icons under public/icons/categories/ had been wrong since June. In the Gemini renders, every icon sat inside a pale bounding box, visible against a light background and invisible against a dark card. I opened the homepage on my phone in October 2026: the “What I build” grid, dark cards, six pale boxes where the icons should have been filling edge-to-edge. The regeneration run in ChatGPT took a morning. PR #566 merged and deployed.

I checked my phone. Still June’s icons.

The host had the new files. An md5 check over HTTP confirmed it: byte-identical to what the repo had just pushed. cPanel had received the push. The bytes on the server were correct. The browser was not requesting the new bytes.

That account covered the cPanel cache trap in full. This article documents the second failure mode that surfaced six weeks earlier. Together they produce the complete picture of what it takes to ship an image refresh on a static site.

What cPanel serves by default

Everything under /icons/ ships with a Cache-Control header set to public with a long max-age. That’s a host-level default I hadn’t set and hadn’t checked. Any HTTP client (browser, CDN, proxy) holds the file for the duration and doesn’t revalidate.

When you push a new file to the same path, the server has it, but the client doesn’t know it exists. Nothing in the response broke; the cache entry is simply still valid.

The fix is URL versioning: rename the file, or add a query string that changes with each regeneration. icon-coding.png?v=20261030 is a different resource from icon-coding.png. The browser has no prior cache entry for it and fetches fresh.

Out of scope: CDN-level purge workflows, cache header renegotiation with the host. URL versioning works without touching server configuration.

The other failure mode: the LCP image that got no hint

Six weeks before the icon regeneration, the article heroes on the /writing route were a different kind of problem. Every hero was a PNG, 476 to 919 kilobytes depending on the image. No WebP. The LCP image was wired through next/image with priority: true, which under a normal Next.js deployment instructs the optimiser to emit a <link rel="preload"> and set fetchpriority="high" on the resulting <img>.

Under images.unoptimized in a static export (which is what a cPanel-hosted Next.js site uses when there’s no image optimisation server available), priority: true on next/image emits a plain <img> tag. No fetchpriority attribute, no preload link. The hint disappears silently.

The browser will find the LCP image eventually. It finds it at the end of the rendering cascade, after layout is complete, which is not where you want it.

The September 2026 sprint addressed both: heroes regenerated to WebP, the LCP <img> updated to carry fetchpriority="high" explicitly rather than relying on next/image’s optimiser to emit it.

The two failures together

Neither failure is exotic. Both are invisible unless you look for them.

The caching trap: deploy a new file to the same path, check your browser, see the old file. Nothing in the deploy output is wrong. The disk write succeeded. The issue is entirely in HTTP cache semantics that I hadn’t configured and the browser was correctly honouring.

The fetchpriority trap: mark the LCP image as priority in next/image, deploy, notice the LCP image loading late. Nothing in the JSX is wrong. The issue is that the attribute I wanted required an optimisation pipeline I wasn’t running.

Both look like image problems. Both present as “images aren’t doing what I expected.” The diagnoses are in different layers: one in HTTP headers, one in Next.js static export behaviour.

What you actually need when refreshing images on a static site

In order:

  • Convert to WebP before putting files into public/. PNG heroes at 476–919 KB are debt, not a starting point.
  • Mark the LCP image with fetchpriority="high" directly on the <img> if you’re using images.unoptimized. next/image’s priority prop will not emit the attribute under a static export.
  • Version the URL on every regeneration. Rename the file or append a query string reflecting the generation date; ?v=20261030 is enough. The URL is the cache key.

None of these are complicated. All three are easy to miss when the focus is on getting the generation right.

The kind covers and the icon grid

The streams work from late October 2026 added five kind covers to public/streams/covers/ as 1280×720 JPEGs, 250 to 340 KB each. The category icons landed in public/icons/categories/ with versioned URLs so cPanel’s cache is not the deciding factor in whether the refresh lands.

The Gemini image harness is gone. scripts/image-harness/ deleted, the two legacy wrappers removed. ChatGPT is now the generator for everything in this class. That’s a separate decision with its own rationale; the filing conventions and .prompt.md sidecars are unchanged.

What I’d tell past-me

Don’t push to the same path twice expecting a different result. If the URL didn’t change, the browser’s cache entry is still valid. Version the URL or you’re delivering the same resource as far as the browser is concerned.

priority: true on next/image is an instruction to the image optimisation server. Under a static export with unoptimized: true, there is no optimisation server. The prop does nothing. Write fetchpriority="high" on the <img> directly.

Check what the server is actually serving before diagnosing the browser. The md5 check over HTTP is five minutes of work. It confirms whether the issue is server-side (wrong bytes) or client-side (correct bytes, wrong cache entry). Those have different fixes.

The caching incident was diagnosed and fixed in October. The fetchpriority issue was diagnosed and fixed in September. They are separate problems that look the same from the outside: images that should have updated and didn’t.

All writing →