Cache image derivatives across builds (#140) (#143)

* Add design spec for caching image derivatives (#140)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Add implementation plan for caching image derivatives (#140)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* ci: cache jekyll_picture_tag derivatives across builds (#140)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: document image derivative caching behaviour (#140)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: correct thumbnail location in CLAUDE.md Image Handling (#140)

The pre-existing sentence said thumbnails cache in assets/thumbs/ and are
gitignored; neither is accurate. JPT writes to _site/assets/thumbs and the
path is not in .gitignore. Aligns with the adjacent caching note.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Delete docs/superpowers/plans/2026-06-28-cache-image-derivatives.md

* Delete docs/superpowers/specs/2026-06-28-cache-image-derivatives-design.md

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: alexwolson

.github/workflows/pages.yml

@@ -78,6 +78,14 @@ jobs:
         env:
           FEEDBACK_TOKEN: ${{ secrets.FEEDBACK_TOKEN }}
 
+      - name: Cache generated image derivatives
+        uses: actions/cache@v4
+        with:
+          path: _site/assets/thumbs
+          key: jpt-thumbs-${{ hashFiles('archives/images/**') }}
+          restore-keys: |
+            jpt-thumbs-
+
       # Outputs to the './_site' directory by default
       - name: Build Jekyll site
         run: |

CLAUDE.md

@@ -69,7 +69,9 @@ Site-wide data is in `_data/`:
 
 ### Image Handling
 
-The `jekyll_picture_tag` plugin processes images from `archives/images/` and caches generated thumbnails in `assets/thumbs/`. This requires `libvips` and `imagemagick` to be installed locally. The `assets/thumbs/` directory is gitignored and regenerated at build time.
+The `jekyll_picture_tag` plugin processes images from `archives/images/` and writes generated thumbnails to `_site/assets/thumbs/` (inside the build output). This requires `libvips` and `imagemagick` to be installed locally. The thumbnails are not committed to git — they are regenerated at build time.
+
+`jekyll_picture_tag` only generates a derivative when its output file is absent in the Jekyll destination (`_site/assets/thumbs`), which Jekyll preserves across builds via `keep_files`. CI caches that directory (`actions/cache`, keyed on `archives/images/**`) so unchanged builds regenerate nothing. Generated filenames embed an MD5 of the source image, so a changed source regenerates correctly; `make clean` forces a full local rebuild.
 
 ## CI/CD
 

README.md

@@ -88,6 +88,9 @@ Ensure your Ruby environment matches the `Gemfile` requirements. Older gem versi
 **Jekyll-GitHub Pages Compatibility**
 GitHub Pages restricts Jekyll plugins for security. See [supported versions](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#plugins) for details.
 
+**Image Derivative Caching**
+CI caches generated image thumbnails (`_site/assets/thumbs`) keyed on the contents of `archives/images/`, so unchanged images are not regenerated. Locally, `_site` persists between builds, so repeat builds are already incremental — running `make clean` wipes `_site` and forces a full regeneration on the next build.
+
 ## Development Scripts
 
 ### Update Submodule