Add CHRONOLOGICAL_ORDER config option to order albums by EXIF date taken

Adds a new yes/no config setting (default no, preserving current behavior)
that orders the main album's photos by EXIF date taken (ascending) instead
of the default filename/shuffle order. Reuses the existing EXIF cache and
tag fallback chain (DateTimeOriginal -> DateTimeDigitized -> DateTime)
already used for tooltips/details/stats, so ordering never disagrees with
what those features show. Photos with no usable EXIF date fall back to
their source file's mtime, staying fully deterministic and crash-free.

CHRONOLOGICAL_ORDER takes precedence over SHUFFLE when both are enabled,
documented in album-photo-select.source.sh and docs/configuration.md.

Wired through the config registry (CONFIG_SPECS), validation, CLI flags
(--chronological/--no-chronological), --print-config, --dry-run,
--verbose logging, and shuriken.json generation metadata. Adds unit and
end-to-end tests covering default-off behavior, EXIF-date ordering with
shuffle precedence, and mtime fallback for EXIF-less photos.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

3 files changed, 40 insertions, 9 deletions

diff --git a/docs/configuration.md b/docs/configuration.md
index e07227a..c2261c0 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -18,7 +18,8 @@ values for the current run.
 | `IMAGE_JOBS` | `3` | Parallel jobs for image processing and HTML template rendering. Positive integer. |
 | `IMAGEMAGICK_TIMEOUT` | `60` | Per-ImageMagick-command timeout in seconds. Positive integer. |
 | `TAR_TIMEOUT` | `120` | Tarball creation timeout in seconds. Positive integer. |
-| `SHUFFLE` | `no` | Randomly shuffle all previews. `yes`/`no`. |
+| `CHRONOLOGICAL_ORDER` | `no` | Order the main album's photos chronologically by EXIF date taken (ascending), falling back to source mtime when a photo has no usable EXIF date. `yes`/`no`. Takes precedence over `SHUFFLE` when both are set. See "Photo ordering" below. |
+| `SHUFFLE` | `no` | Randomly shuffle all previews. `yes`/`no`. Ignored when `CHRONOLOGICAL_ORDER=yes`. |
 | `SPLASH_PAGE` | `yes` | Generate a splash landing page at `index.html`. `yes`/`no`. |
 | `DETAILS_PAGE` | `yes` | Generate each photo's `*-details.html` page (and its "Details" link). `yes`/`no`. See "Details pages" below. |
 | `STATS_PAGE` | `no` | Generate the EXIF stats site under `stats/`. `yes`/`no`. |
@@ -65,6 +66,26 @@ does not leave stale `*-details.html` files behind: generation stages the new
 output in a fresh directory and atomically replaces `DIST_DIR`, so files an
 older generation wrote but the current run does not produce are naturally gone.
 
+## Photo ordering
+
+By default the main album's photos are listed in plain filename order, or in a
+random/seeded shuffle when `SHUFFLE=yes` (see [generation.md](generation.md)
+for reproducibility). Set `CHRONOLOGICAL_ORDER=yes` (or pass `--chronological`)
+to instead order them chronologically by EXIF date taken (ascending), reusing
+the same `DateTimeOriginal` -> `DateTimeDigitized` -> `DateTime` tag fallback
+chain, and the same per-photo EXIF cache, as the "Taken:" tooltip field and the
+details page. A photo with none of those three tags falls back to its source
+file's modification time, so ordering is always fully deterministic and never
+crashes on EXIF-less photos (screenshots, downloaded images, ...); photos with
+a real EXIF date always sort before mtime-fallback photos, so an approximate
+fallback never displaces a genuine timestamp.
+
+**`CHRONOLOGICAL_ORDER` takes precedence over `SHUFFLE`** when both are set to
+`yes`: a chronological album is meant to read as a timeline, so an enabled
+shuffle is silently ignored rather than re-scrambling it. This is a config-level
+choice, not a validation error, so toggling `SHUFFLE` while experimenting does
+not require also touching `CHRONOLOGICAL_ORDER`.
+
 ## Supported source images
 
 Only regular files found directly in `INCOMING_DIR` (not in subdirectories) with
@@ -84,8 +105,9 @@ The checks (details in `src/lib/config.validate.source.sh`):
   `IMAGEMAGICK_TIMEOUT`, `TAR_TIMEOUT`; `HEIGHT` is an optional positive integer.
 * **Percentage (0-100 integer)**: `THUMB_SUBDIVIDE_PERCENT`,
   `THUMB_FEATURE_PERCENT`.
-* **`yes`/`no` settings**: `SHUFFLE`, `SPLASH_PAGE`, `DETAILS_PAGE`,
-  `STATS_PAGE`, `TARBALL_INCLUDE`, `SYNC_DELETE` (where applicable).
+* **`yes`/`no` settings**: `CHRONOLOGICAL_ORDER`, `SHUFFLE`, `SPLASH_PAGE`,
+  `DETAILS_PAGE`, `STATS_PAGE`, `TARBALL_INCLUDE`, `SYNC_DELETE` (where
+  applicable).
 * **Readable input**: `INCOMING_DIR` must be a readable directory; `TEMPLATE_DIR`
   must be a readable directory containing the required templates (plus `splash`
   when `SPLASH_PAGE=yes`, and `details` when `DETAILS_PAGE=yes`).
@@ -107,9 +129,10 @@ Generation stops before writing album output when validation fails.
 `CONFIG_SOURCE`, `INCOMING_DIR`, `DIST_DIR`, `TEMPLATE_DIR`, `FAVICON`,
 `SOURCE_URL`, `TITLE`, `HEIGHT`, `THUMBHEIGHT`, `MAXPREVIEWS`,
 `THUMB_SUBDIVIDE_PERCENT`, `THUMB_FEATURE_PERCENT`, `IMAGE_JOBS`,
-`IMAGEMAGICK_TIMEOUT`, `RANDOM_SEED`, `SHUFFLE`, `SPLASH_PAGE`, `DETAILS_PAGE`,
-`STATS_PAGE`, `TARBALL_INCLUDE`, `TARBALL_SUFFIX`, `TAR_TIMEOUT`, `TAR_OPTS`,
-`SYNC_DELETE`, `SYNC_DESTINATIONS`, `ORIGINAL_BASEPATH`.
+`IMAGEMAGICK_TIMEOUT`, `RANDOM_SEED`, `CHRONOLOGICAL_ORDER`, `SHUFFLE`,
+`SPLASH_PAGE`, `DETAILS_PAGE`, `STATS_PAGE`, `TARBALL_INCLUDE`,
+`TARBALL_SUFFIX`, `TAR_TIMEOUT`, `TAR_OPTS`, `SYNC_DELETE`,
+`SYNC_DESTINATIONS`, `ORIGINAL_BASEPATH`.
 
 Scalar values use Bash `%q` quoting; `TAR_OPTS` and `SYNC_DESTINATIONS` are
 normalized to Bash array assignments, so the output can be parsed by shell
diff --git a/docs/generation.md b/docs/generation.md
index 126f2bd..3941800 100644
--- a/docs/generation.md
+++ b/docs/generation.md
@@ -90,6 +90,12 @@ timestamps, and `--shuffle` preview order remain non-deterministic. Set
 choices repeatable for stable tests or reproducible album builds. Use the same
 seed and inputs to produce the same HTML.
 
+`CHRONOLOGICAL_ORDER=yes` (see "Photo ordering" in
+[configuration.md](configuration.md)) is always deterministic regardless of
+`RANDOM_SEED`: it orders by each photo's EXIF date taken (with a source-mtime
+fallback), so it needs no seed to repeat, and it takes precedence over
+`SHUFFLE` when both are enabled.
+
 ## Parallelism and timeouts
 
 ImageMagick photo processing and per-photo HTML template rendering run in
@@ -111,9 +117,9 @@ metadata records:
 * generated photo, thumbnail, and HTML file counts;
 * tarball status (included + file);
 * effective settings (title, height, thumbheight, maxpreviews, subdivide
-  percent, feature percent, image jobs, random seed, shuffle, splash page,
-  details page, stats page, original basepath) useful for debugging a published
-  album.
+  percent, feature percent, image jobs, random seed, chronological order,
+  shuffle, splash page, details page, stats page, original basepath) useful for
+  debugging a published album.
 
 ## Favicon
 
diff --git a/docs/usage.md b/docs/usage.md
index 9436e36..5cb35b5 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -72,6 +72,8 @@ config variable documented in [configuration.md](configuration.md).
 | `--feature PERCENT` | `THUMB_FEATURE_PERCENT` |
 | `--image-jobs N` | `IMAGE_JOBS` |
 | `--random-seed VALUE` | `RANDOM_SEED` |
+| `--chronological` | `CHRONOLOGICAL_ORDER=yes` |
+| `--no-chronological` | `CHRONOLOGICAL_ORDER=no` |
 | `--shuffle` | `SHUFFLE=yes` |
 | `--no-shuffle` | `SHUFFLE=no` |
 | `--splash` | `SPLASH_PAGE=yes` |