Improve batch image fetch speed and document the pipeline.

Add random queue sampling and a 10s per-painting deadline for fetch-images batches, cap HTTP timeouts to the remaining budget, and update docs plus newly fetched artwork files.

Co-authored-by: Cursor <cursoragent@cursor.com>

Documentation/setup.md

@@ -29,6 +29,7 @@ Optional script tuning:
 | Variable | Used by | Description |
 |----------|---------|-------------|
 | `MIN_PAINTINGS` | `expand-catalog` | Minimum paintings per artist (default `6`) |
+| `FETCH_MAX_WAIT_SEC` | `fetch-images` | Max seconds per painting in batch runs (default `10`) |
 
 `.env` is git-ignored; never commit passwords.
 
@@ -64,11 +65,12 @@ After a fresh seed, run these to match a fully populated local install:
 npm run fetch-artist-bios          # bio_short / bio_full from Wikipedia
 npm run expand-catalog             # famous works for artists below MIN_PAINTINGS
 npm run update-influences          # painting influence graph for detail view + hall exits
-npm run fetch-images -- --artist="Gustav Klimt"   # repeat per artist or omit --artist for all
+npm run fetch-images -- --limit=50                # random sample; 10s max per painting (default)
+npm run fetch-images -- --limit=50 --max-wait=120 # same batch size, longer lookup per work
 cd client && npm run build && cd ..
 ```
 
-Image fetch is rate-limited (~3.5 s between external requests) and can take hours for the full catalog. Fetch per artist, or rely on on-demand resolution when viewing a painting in the detail view.
+Image fetch can take hours for the full catalog (~900+ missing works after seed). Use **`npm run fetch-images -- --limit=N`** for random batches (10s per painting by default), **`--artist="…"`** for one artist in catalog order, or on-demand resolution when viewing a painting in the detail view.
 
 ## Run
 
@@ -99,8 +101,9 @@ Open http://localhost:3001 (or your configured `PORT`).
 | `npm run expand-catalog -- --fetch-images` | ↑ | Also download images for new rows (slow) |
 | `npm run fetch-images` | `scripts/fetch-missing-images.js` | Search Wikipedia, Commons, museums for missing files |
 | `npm run search-missing-paintings` | ↑ (alias) | Same as `fetch-images` |
-| `npm run fetch-images -- --artist="Name"` | ↑ | Limit to one artist |
-| `npm run fetch-images -- --limit=50` | ↑ | Process at most N paintings |
+| `npm run fetch-images -- --artist="Name"` | ↑ | Limit to one artist (catalog order) |
+| `npm run fetch-images -- --limit=50` | ↑ | Random sample of N missing paintings |
+| `npm run fetch-images -- --limit=50 --max-wait=120` | ↑ | Random batch; 120s cap per painting |
 | `npm run fetch-images -- --discover-only --limit=20` | ↑ | Fix `wikipedia_title` via search only |
 | `npm run regenerate-thumbnails` | `scripts/regenerate-thumbnails.js` | Rebuild all thumbs from full local files |
 | `npm run audit-painting-images` | `scripts/audit-painting-images.js` | List thumb/full aspect-ratio mismatches |
@@ -143,7 +146,8 @@ After clone: copy `.env.example` → `.env`, install dependencies, run `npm run
 | 500 on all `/api/*` | Wrong `.env` or Postgres down | Check connection, logs |
 | “Biographical information not yet available” | Bios not fetched | `npm run fetch-artist-bios` |
 | Artist hall has only 1–2 paintings | Catalog not expanded | `npm run expand-catalog`; extend `famous-paintings-data.js` |
-| Black frames / canvas covers in 3D gallery | No local image for painting | `npm run fetch-images -- --artist="…"` or `POST …/preload-images` after fetch |
+| Black frames / canvas covers in 3D gallery | No local image for painting | `npm run fetch-images -- --limit=50` or `--artist="…"`; then `POST …/preload-images` |
+| Many `⏱ timeout` lines in fetch batch | Default 10s cap too short for hard works | `--max-wait=120` or raise `FETCH_MAX_WAIT_SEC` |
 | White/grey flicker on frames | Texture loading or z-fighting with wall | Rebuild client (`cd client && npm run build`); ensure latest `VirtualGallery.tsx` |
 | Wrong painting in 3D gallery frame | Stale or mismatched thumbnail file | `npm run regenerate-thumbnails`; gallery prefers full `image_path` |
 | Wrong painting image (fetch) | Bad museum / search match on first download | Add entry to `DIRECT_IMAGE_OVERRIDES` in `scripts/image-fetcher.js`, re-fetch file |