PR #566 merged. Deploy triggered. Browser opened.

The “What I Build” grid loaded with the June 2026 icons — pale boxes on dark cards, unchanged. The ChatGPT rerun had produced better files, the deploy had moved them to the host, and the browser had not moved on.

Not a deploy failure. A cache one.

The server had the right files

First check: confirm the host. The site is a Next.js static export deployed to cPanel shared hosting via FTP. I retrieved each icon by URL and MD5-checked it against the repo. All six files under public/icons/categories/ came back byte-identical to the committed versions. The deploy had succeeded. The host had the October files.

The browser had the June files. The host and the browser disagreed. The host was right.

What the cache header said

cPanel sets a year-long max-age by default on static assets served under /icons/. The browser had fetched the June Gemini icons when they first landed, received that header, and filed them locally. It was told, unambiguously, not to check again for twelve months.

It obeyed. This is correct browser behaviour.

The assumption embedded in that header is that if the content changes, the URL changes too. I had violated it by deploying new files to the same paths as the old ones. The header doesn’t distinguish between “same content, stable” and “new content, different file”. It only reads the URL, and the URL hadn’t changed.

Why clearing the cache misses the point

The reflex when this happens is usually “clear the browser cache” and move on. That works once, on your machine, today. It doesn’t fix the user who fetched the June icons two weeks ago and hasn’t cleared anything. It doesn’t fix the stream covers that landed that same week, or the next asset that gets deployed to the same path as its predecessor.

A cache clear is incident response. URL versioning is architecture.

cPanel shared hosting provides no programmatic cache invalidation. No API, no CDN edge to flush, no Cloudflare zone to purge. The only lever available at deploy time is the URL itself.

The fix

The fix applied after PR #566: version the category icon URLs.

When the reference in source carries a version marker, the browser has never seen that URL. Its cache has no entry for it. It fetches. The year-long max-age is irrelevant, because the cache miss is built into the URL.

This is not a workaround. It is how content-addressable delivery is supposed to work. The URL is the cache key; changing the content means changing the key. Browser caches, CDN edges, and reverse proxies all respect this. No cooperation required from the server.

Out of scope: automatic asset fingerprinting across the full public/ tree. The site is a Next.js static export deployed via FTP, not a Vercel-hosted instance with a framework-managed content-hash pipeline. Manual URL versioning on explicit asset updates is the right tool for this deployment model. Automating it across the board is a separate sprint.

Why the icon rerun hit this

Improving on the earlier account of the caching discovery: the category icons were June 2026 Gemini renders, produced before the Gemini image harness was retired. By October they were sitting in pale boxes on dark cards. The contrast model had shifted and the icons hadn’t kept up. The rerun went through ChatGPT; the Gemini harness had been retired and deleted from scripts/image-harness/ on 2026-10-26, the same week as the rerun. Six replacement icons were committed and deployed via PR #566. Same paths. New files.

The June icons had a year-long cache. The October icons had the same URLs.

After versioning the URLs, the browser fetched the new icons on next load. The pale-box problem was gone.

The contrast with the WebP migration

For comparison: in September 2026, every article hero was converted from PNG to WebP and the LCP image was given explicit fetchpriority handling. That migration busted the cache automatically. The format change was a URL change, from .png to .webp, and no browser had a cached entry for the new paths.

The category icon rerun didn’t get that. Same format, same filename, same path. Better content, identical address.

That’s the distinction. Format migrations, path restructures, and filename changes all bust the cache incidentally. In-place reruns, where an improved file sits at the same address, don’t. Any workflow that improves a file without changing its path needs an explicit versioning step. The WebP migration was an accidental win on caching. The icon rerun was an accidental loss.

What the pipeline now does

Every asset update that replaces a file in place now carries a URL version increment. No automated lint enforces this yet; it is a code discipline requirement. The working rule: if the content changes, the URL changes. If the URL doesn’t change, the deploy is not done.

That reframes what “a successful deploy” means on a cPanel host. Uploading the right files to the right paths is necessary. It is not sufficient. The client-side cache also needs a reason to fetch, and on a host with a year-long max-age and no invalidation API, the only mechanism available is the URL.

If you’re deploying to cPanel

Three points, in order of impact.

Version the URL when you replace a file. A query parameter (?v=2) works for direct browser caches. A path segment (/icons/v2/) is more resilient across proxies and CDN layers. Either beats a file-only replacement.

Treat the deploy as incomplete until the URL is updated. On a host with a year-long max-age and no invalidation API, there is no other mechanism. A file replacement without a URL change is a half-deploy.

Assume the user has not cleared their cache. On shared hosting serving the cPanel default, assume the year-long instruction was followed and that a fresh fetch happens only when the URL is new to the browser.

The year-long max-age is not a misconfiguration. It is a sensible default for assets presumed stable. The contract it creates is the right contract: stable content at stable URLs, changed content at new URLs. Violating it by swapping content at a fixed URL is the error. The pipeline now treats that contract as a constraint, not a background detail.

All writing →