# Gallery generator contract

This directory is the home for gallery generator scripts. Generators stay
runnable and reviewable here instead of in scratch. The checker
(`check.py`) validates sources against the contract below.

## Output contract

- Filenames: lowercase `flyer-<slug>.jpg` or `meme-<slug>.jpg`, hyphen
  slugs, no spaces, no dates, no version suffixes.
- Sizes: flyers exactly 1080x1350, memes exactly 1080x1080. The 1280x720
  memes on disk are legacy and grandfathered; new works never use it.
- Format: JPEG, sRGB, quality high enough that text stays crisp.
- Captions: one English line per work, plain words, no em or en dashes.
  Captions live in `molodetz/gallery.py` next to the filename entry.

## Handoff procedure

1. Generate into a scratch directory, never straight into `static/media`.
2. Run `make check-gallery GALLERY_DIR=<scratch>` (or point the checker
   at the scratch dir directly). Fix every error; warnings are advisory.
3. Move the files into `molodetz/static/media`, add the `GALLERY` entries
   with captions, run `make check-gallery` again with no arguments.
4. Commit code plus media together, deploy, then press *Resync gallery*
   under *Admin, Gallery* (staging) or rely on the boot sync (production
   rebuild).

## Rules

- Never invent catalogue entries outside `GALLERY`: the sync only reads
  what is catalogued, and the checker fails stray files.
- Near-duplicates (perceptual hash distance 2 or less) are skipped by
  the sync and failed by the checker. Regenerate instead of renaming.
- Retired works stay listed in `RETIRED_GALLERY` so every environment
  converges on the same visible set.