diff --git a/.env.local.example b/.env.local.example
index 255043a..d2cc2ea 100644
--- a/.env.local.example
+++ b/.env.local.example
@@ -19,6 +19,21 @@ SITE_SUBTITLE=A visual journal
 # Cache TTL in seconds (integer >= 0, default: 300 = 5 minutes)
 CACHE_TTL=300
 
+# Cache-buster for image and video URLs (any string, default: empty = off).
+# Images are served with a one-year immutable cache, so browsers never
+# revalidate them. If you regenerate thumbnails in Immich, or rotate/edit a
+# photo, the asset ID stays the same and visitors keep seeing the old version.
+# Bump this value (e.g. 1 → 2) to change every image URL at once and force a
+# refetch. Leave it unset in normal operation.
+# IMAGE_CACHE_VERSION=1
+
+# How long to wait for a response from Immich, in milliseconds
+# (integer, minimum 1000, default: 15000 = 15 seconds).
+# Bounds the wait for a *response* only — downloading a large photo or a long
+# video is not capped by this. Raise it if metadata search on very large albums
+# times out; lower it to fail faster when Immich is unreachable.
+# IMMICH_TIMEOUT_MS=15000
+
 # Rate limit for image proxy (integer >= 1, requests per minute per IP, default: 120)
 # RATE_LIMIT_RPM=120
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 7133589..59be0de 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -75,7 +75,9 @@ Singleton `ImmichClient` class exported as `immich`. All Immich API calls are se
 | `GET /api/admin/albums` | Browse all shared Immich albums (admin-only) |
 | `POST /api/admin/reload` | Invalidate config + Immich cache |
 
-The image proxy maps requested pixel widths (`?w=`) to Immich size tiers: `≤250px→thumbnail`, `≤1440px→preview`, `>1440px→original`.
+The image proxy maps requested pixel widths (`?w=`) to Immich size tiers: `≤250px→thumbnail`, `≤1440px→preview`, `>1440px→original` (`lib/imageSize.ts`).
+
+`?size=` (written by `lib/urls.ts`) acts as a **ceiling**, not an override. When both parameters are present the smaller tier wins, so `?w=` can narrow the request but never widen it — `next/image` emits widths up to 3840, so letting width win outright would serve full-size originals to every large display.
 
 ### Routing (`app/[...path]/page.tsx`)
 
@@ -119,10 +121,12 @@ Visual page builder and settings editor at `/admin`. Enabled by setting `ADMIN_P
 
 After saving, `invalidateConfigCache()` is called so the next request picks up the new YAML without restart.
 
-### Middleware (`middleware.ts`)
+### Proxy (`proxy.ts`)
 
 Applies CSP (with per-request nonce), HSTS, and other security headers on all non-API, non-static routes. The nonce is passed to pages via the `x-nonce` request header.
 
+Next.js 16 renamed the `middleware` file convention to `proxy`: the file is `proxy.ts` and it exports `proxy()` (not `middleware()`). The `config.matcher` export is unchanged.
+
 ## Code conventions
 
 - **TypeScript strict mode** — no untyped `any`; use `@ts-expect-error` (not `@ts-ignore`) with a comment when suppressing type errors.
diff --git a/README.md b/README.md
index 0086b5b..61b301e 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,8 @@ IMMICH_API_KEY=your-api-key
 SITE_TITLE=My Photography            # default: "Gallery"
 SITE_SUBTITLE=A visual journal        # default: empty
 CACHE_TTL=300                          # seconds, default: 300
+IMMICH_TIMEOUT_MS=15000                # Immich response wait, default: 15000
+IMAGE_CACHE_VERSION=1                  # bump to bust browser image caches, default: off
 RATE_LIMIT_RPM=1500                    # requests/min/IP, default: 1500
 AUTH_SECRET=long-random-string        # required in production
 TRUSTED_PROXY_HOPS=1                   # reverse proxies in front, default: 0
diff --git a/app/[...path]/PhotoGrid.tsx b/app/[...path]/PhotoGrid.tsx
index d69bf11..0288e57 100644
--- a/app/[...path]/PhotoGrid.tsx
+++ b/app/[...path]/PhotoGrid.tsx
@@ -18,7 +18,6 @@ export interface PhotoItem {
   type: 'image' | 'video';
   thumbUrl: string;
   previewUrl: string;
-  originalUrl: string;
   videoUrl?: string;
   exifUrl: string;
   blurDataURL?: string;
diff --git a/app/[...path]/page.tsx b/app/[...path]/page.tsx
index 1792a61..7e014d0 100644
--- a/app/[...path]/page.tsx
+++ b/app/[...path]/page.tsx
@@ -10,13 +10,13 @@
  *     with back-link to the subpage
  */
 
-import Link from 'next/link';
-import Image from 'next/image';
 import { cookies } from 'next/headers';
 import type { Metadata } from 'next';
 import { immich, type ImmichAsset } from '@/lib/immich';
 import { notFound } from 'next/navigation';
-import { PhotoGrid, type PhotoItem } from './PhotoGrid';
+// Only the type: rendering moved to AlbumDetailView/SubpageGridView, which
+// import the component themselves.
+import type { PhotoItem } from './PhotoGrid';
 import {
   imageUrl,
   exifUrl,
@@ -29,7 +29,6 @@ import { encodeAssetId } from '@/lib/tokens';
 import { getConfig, type GridConfig } from '@/lib/config';
 import { isProtected, isAuthenticated } from '@/lib/auth';
 import PasswordGate from '@/components/PasswordGate';
-import { BackLink } from '@/components/BackLink';
 import { AlbumDetailView } from './AlbumDetailView';
 import { SubpageGridView } from './SubpageGridView';
 
@@ -103,7 +102,6 @@ function toPhotoItems(assets: ImmichAsset[], showExif: boolean): PhotoItem[] {
         type: isVideo ? 'video' : 'image',
         thumbUrl: imageUrl(a.id, 'preview'),
         previewUrl: imageUrl(a.id, 'preview'),
-        originalUrl: imageUrl(a.id, 'original'),
         ...(isVideo ? { videoUrl: videoUrl(a.id) } : {}),
         exifUrl: exifUrl(a.id),
         ...(ph ? { blurDataURL: ph.blurDataURL, dominantColor: ph.dominantColor } : {}),
diff --git a/app/admin/layout.tsx b/app/admin/layout.tsx
index 828941e..54ca9b7 100644
--- a/app/admin/layout.tsx
+++ b/app/admin/layout.tsx
@@ -8,7 +8,7 @@ export const metadata: Metadata = {
 /**
  * Required for the CSP nonce. The admin page is a pure client component, so
  * Next.js would statically prerender it at build time — and a prerendered HTML
- * file cannot carry the per-request nonce that middleware.ts issues. Since the
+ * file cannot carry the per-request nonce that proxy.ts issues. Since the
  * CSP uses 'strict-dynamic' (which makes 'self' inert), unnonced script tags
  * are blocked and the panel never hydrates. Rendering per request lets Next.js
  * stamp the nonce onto the script tags it emits.
diff --git a/app/api/admin/auth/route.ts b/app/api/admin/auth/route.ts
index aa97e44..b167b68 100644
--- a/app/api/admin/auth/route.ts
+++ b/app/api/admin/auth/route.ts
@@ -7,7 +7,7 @@ import {
   COOKIE_NAME,
   SESSION_DURATION_MS,
 } from '@/lib/admin/auth';
-import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
+import { checkRateLimit, getClientIp, retryAfterSeconds } from '@/lib/rate-limit';
 
 /** Admin login attempts per minute per IP — the highest-value credential in the app. */
 const ADMIN_AUTH_RPM = 5;
@@ -21,7 +21,7 @@ export async function POST(request: NextRequest) {
       { error: 'Too many requests' },
       {
         status: 429,
-        headers: { 'Retry-After': String(Math.ceil((rl.resetAt - Date.now()) / 1000)) },
+        headers: { 'Retry-After': String(retryAfterSeconds(rl.resetAt)) },
       },
     );
   }
diff --git a/app/api/admin/gallery/route.ts b/app/api/admin/gallery/route.ts
index aa39ae0..3374f23 100644
--- a/app/api/admin/gallery/route.ts
+++ b/app/api/admin/gallery/route.ts
@@ -2,7 +2,7 @@ import { NextResponse } from 'next/server';
 import { revalidatePath } from 'next/cache';
 import { isAdminAuthenticated, isAdminEnabled } from '@/lib/admin/auth';
 import { readGalleryYaml, writeGalleryYaml } from '@/lib/admin/yaml-service';
-import { invalidateConfigCache } from '@/lib/config';
+import { invalidateConfigCache, deriveGallery } from '@/lib/config';
 import { immich } from '@/lib/immich';
 import type { GalleryYaml } from '@/lib/config/schema';
 
@@ -39,13 +39,34 @@ export async function PUT(request: Request) {
     return NextResponse.json({ error: 'Invalid hero format' }, { status: 400 });
   }
 
+  // Run the *real* derivation before writing. getConfig() throws on a gallery
+  // with no albums and no subpages, a subpage with no name, or a subpage with
+  // neither albums nor sections — all of which the page builder can produce.
+  // Writing one used to report "Saved successfully" and then take the public
+  // site down until someone noticed.
+  //
+  // Calling deriveGallery rather than re-checking those conditions here is
+  // deliberate: a second copy of the rules would drift from the first. So is
+  // validating before the write rather than rolling back after — a rollback
+  // leaves a window in which other requests read the broken config.
+  try {
+    deriveGallery(gallery);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : 'Invalid gallery structure';
+    console.warn('[Admin] Rejected an unloadable gallery.yaml:', reason);
+    return NextResponse.json({ error: reason }, { status: 400 });
+  }
+
   try {
     await writeGalleryYaml(gallery);
     invalidateConfigCache();
     immich.invalidateAll();
     // Revalidate all pages so the homepage picks up new hero images immediately
     revalidatePath('/', 'layout');
-    return NextResponse.json({ success: true, message: 'Saved successfully. Backup of previous version created.' });
+    return NextResponse.json({
+      success: true,
+      message: 'Saved successfully. Backup of previous version created.',
+    });
   } catch (err) {
     console.error('[Admin] Failed to write gallery.yaml:', err);
     return NextResponse.json({ error: 'Failed to save gallery config' }, { status: 500 });
diff --git a/app/api/auth/route.ts b/app/api/auth/route.ts
index 8e709a4..c12983c 100644
--- a/app/api/auth/route.ts
+++ b/app/api/auth/route.ts
@@ -5,7 +5,7 @@
 
 import { NextRequest, NextResponse } from 'next/server';
 import { authenticate, isProtected } from '@/lib/auth';
-import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
+import { checkRateLimit, getClientIp, retryAfterSeconds } from '@/lib/rate-limit';
 
 /** Tight limit for auth attempts — 10 per minute per IP. */
 const AUTH_RPM = 10;
@@ -21,7 +21,7 @@ export async function POST(request: NextRequest) {
       {
         status: 429,
         headers: {
-          'Retry-After': String(Math.ceil((resetAt - Date.now()) / 1000)),
+          'Retry-After': String(retryAfterSeconds(resetAt)),
           'X-RateLimit-Limit': String(AUTH_RPM),
           'X-RateLimit-Remaining': String(remaining),
         },
@@ -59,7 +59,7 @@ export async function POST(request: NextRequest) {
       );
     }
 
-    const setCookie = authenticate(slug, password, type);
+    const setCookie = await authenticate(slug, password, type);
     if (!setCookie) {
       return NextResponse.json({ error: 'Invalid password' }, { status: 401 });
     }
diff --git a/app/api/exif/[id]/route.ts b/app/api/exif/[id]/route.ts
index 59f7ce6..3c48435 100644
--- a/app/api/exif/[id]/route.ts
+++ b/app/api/exif/[id]/route.ts
@@ -6,10 +6,10 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server';
-import { immich } from '@/lib/immich';
+import { immich, ImmichUnavailableError } from '@/lib/immich';
 import { decodeAssetId } from '@/lib/tokens';
 import { getConfig } from '@/lib/config';
-import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
+import { checkRateLimit, getClientIp, retryAfterSeconds } from '@/lib/rate-limit';
 
 export async function GET(request: NextRequest, { params }: { params: Promise<{ id: string }> }) {
   const config = getConfig();
@@ -24,9 +24,15 @@ export async function GET(request: NextRequest, { params }: { params: Promise<{
   const { success, resetAt } = checkRateLimit(`exif:${ip}`, config.rateLimitRpm);
 
   if (!success) {
-    const retryAfter = Math.ceil((resetAt - Date.now()) / 1000);
+    const retryAfter = retryAfterSeconds(resetAt);
     console.warn(`[EXIF API] ⚠️ Rate limit exceeded for IP: ${ip}. Retry after ${retryAfter}s`);
-    return NextResponse.json({ error: 'Too many requests' }, { status: 429 });
+    return NextResponse.json(
+      { error: 'Too many requests' },
+      {
+        status: 429,
+        headers: { 'Retry-After': String(retryAfter), 'Cache-Control': 'no-store' },
+      },
+    );
   }
 
   const { id: token } = await params;
@@ -37,7 +43,22 @@ export async function GET(request: NextRequest, { params }: { params: Promise<{
     return NextResponse.json({ error: 'Invalid token' }, { status: 400 });
   }
 
-  const asset = await immich.getAssetInfo(assetId);
+  let asset;
+  try {
+    asset = await immich.getAssetInfo(assetId);
+  } catch (error) {
+    // Immich is down, not "this asset has no EXIF" — say so, so the lightbox
+    // can retry rather than caching a 404 for a photo that does have data.
+    if (error instanceof ImmichUnavailableError) {
+      console.error(`[EXIF API] Immich unavailable for ${assetId}:`, error.message);
+      return NextResponse.json(
+        { error: 'Immich is currently unavailable' },
+        { status: 503, headers: { 'Retry-After': '30', 'Cache-Control': 'no-store' } },
+      );
+    }
+    throw error;
+  }
+
   if (!asset?.exifInfo) {
     return NextResponse.json({ error: 'No EXIF data' }, { status: 404 });
   }
diff --git a/app/api/health/route.ts b/app/api/health/route.ts
index 168d89d..bed8aed 100644
--- a/app/api/health/route.ts
+++ b/app/api/health/route.ts
@@ -7,7 +7,7 @@
 
 import { NextRequest, NextResponse } from 'next/server';
 import { immich } from '@/lib/immich';
-import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
+import { checkRateLimit, getClientIp, retryAfterSeconds } from '@/lib/rate-limit';
 import { getConfig } from '@/lib/config';
 
 const startTime = Date.now();
@@ -30,7 +30,7 @@ export async function GET(request: NextRequest) {
       {
         status: 429,
         headers: {
-          'Retry-After': String(Math.ceil((resetAt - Date.now()) / 1000)),
+          'Retry-After': String(retryAfterSeconds(resetAt)),
           'X-RateLimit-Limit': String(rateLimitRpm),
           'X-RateLimit-Remaining': String(remaining),
         },
diff --git a/app/api/image/[id]/route.ts b/app/api/image/[id]/route.ts
index f28c4ff..c4bd654 100644
--- a/app/api/image/[id]/route.ts
+++ b/app/api/image/[id]/route.ts
@@ -8,21 +8,11 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server';
-import { immich, ImageSize } from '@/lib/immich';
+import { immich, ImmichUnavailableError } from '@/lib/immich';
+import { resolveImageSize } from '@/lib/imageSize';
 import { decodeAssetId } from '@/lib/tokens';
 import { getConfig } from '@/lib/config';
-import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
-
-const VALID_SIZES: ImageSize[] = ['thumbnail', 'preview', 'original'];
-
-/**
- * Map a requested pixel width to the best Immich size tier.
- */
-function widthToSize(w: number): ImageSize {
-  if (w <= 250) return 'thumbnail';
-  if (w <= 1440) return 'preview';
-  return 'original';
-}
+import { checkRateLimit, getClientIp, retryAfterSeconds } from '@/lib/rate-limit';
 
 export async function GET(request: NextRequest, { params }: { params: Promise<{ id: string }> }) {
   // ── Rate limiting ──────────────────────────────────
@@ -30,12 +20,22 @@ export async function GET(request: NextRequest, { params }: { params: Promise<{
   const { success, remaining, resetAt } = checkRateLimit(`image:${ip}`, getConfig().rateLimitRpm);
 
   if (!success) {
-    const retryAfter = Math.ceil((resetAt - Date.now()) / 1000);
+    const retryAfter = retryAfterSeconds(resetAt);
     const userAgent = request.headers.get('user-agent') || 'unknown';
     console.warn(
       `[Image API] ⚠️ Rate limit exceeded for IP: ${ip} (UA: ${userAgent}). Retry after ${retryAfter}s`,
     );
-    return NextResponse.json({ error: 'Too many requests' }, { status: 429 });
+    // Without Retry-After the browser and next/image back off on their own
+    // schedule — a retry storm against a server that just said it was
+    // overloaded, and one page issues ~50 of these requests. no-store because
+    // the success path serves this URL as `immutable`.
+    return NextResponse.json(
+      { error: 'Too many requests' },
+      {
+        status: 429,
+        headers: { 'Retry-After': String(retryAfter), 'Cache-Control': 'no-store' },
+      },
+    );
   }
 
   const { id: token } = await params;
@@ -47,23 +47,19 @@ export async function GET(request: NextRequest, { params }: { params: Promise<{
     return NextResponse.json({ error: 'Invalid token' }, { status: 400 });
   }
 
-  // Determine size: prefer explicit ?size=, then infer from ?w=
-  const sizeParam = request.nextUrl.searchParams.get('size');
-  const widthParam = request.nextUrl.searchParams.get('w');
-
-  let size: ImageSize = 'preview';
-  if (sizeParam && VALID_SIZES.includes(sizeParam as ImageSize)) {
-    size = sizeParam as ImageSize;
-  } else if (widthParam) {
-    const w = parseInt(widthParam, 10);
-    if (!isNaN(w) && w > 0) {
-      size = widthToSize(w);
-    }
-  }
+  const size = resolveImageSize(
+    request.nextUrl.searchParams.get('size'),
+    request.nextUrl.searchParams.get('w'),
+  );
 
   // ── Browser Cache Optimization ─────────────────────
-  // Use the opaque token to generate a safe ETag without leaking Immich UUIDs
-  const etag = `W/"${token}-${size}"`;
+  // Use the opaque token to generate a safe ETag without leaking Immich UUIDs.
+  // IMAGE_CACHE_VERSION participates so that a bump is not defeated by a client
+  // replaying the old ETag against the new URL — the response is served
+  // `immutable`, so this only matters after expiry or a cache eviction, but a
+  // matching ETag across two different URLs would be wrong either way.
+  const cacheVersion = request.nextUrl.searchParams.get('v') ?? '';
+  const etag = `W/"${token}-${size}${cacheVersion ? `-${cacheVersion}` : ''}"`;
   if (request.headers.get('if-none-match') === etag) {
     return new NextResponse(null, {
       status: 304,
@@ -75,10 +71,29 @@ export async function GET(request: NextRequest, { params }: { params: Promise<{
     });
   }
 
-  const result = await immich.streamAsset(assetId, size);
+  let result;
+  try {
+    result = await immich.streamAsset(assetId, size);
+  } catch (error) {
+    // An outage must not look like a deleted photo. These URLs are served with
+    // `immutable` on success, and a bare 404 is heuristically cacheable — so
+    // without no-store the browser can pin a broken image for the whole session.
+    if (error instanceof ImmichUnavailableError) {
+      console.error(`[Image API] Immich unavailable for ${assetId}:`, error.message);
+      return NextResponse.json(
+        { error: 'Immich is currently unavailable' },
+        { status: 503, headers: { 'Retry-After': '30', 'Cache-Control': 'no-store' } },
+      );
+    }
+    throw error;
+  }
+
   if (!result) {
     console.error(`[Image API] ❌ Asset not found in Immich: ${assetId} (Size: ${size})`);
-    return NextResponse.json({ error: 'Asset not found' }, { status: 404 });
+    return NextResponse.json(
+      { error: 'Asset not found' },
+      { status: 404, headers: { 'Cache-Control': 'no-store' } },
+    );
   }
 
   let contentType = result.contentType.toLowerCase();
diff --git a/app/api/map/route.ts b/app/api/map/route.ts
index 00d244c..f789512 100644
--- a/app/api/map/route.ts
+++ b/app/api/map/route.ts
@@ -10,7 +10,8 @@ import { getConfig } from '@/lib/config';
 import { imageUrl } from '@/lib/urls';
 import { isAuthenticated } from '@/lib/auth';
 import { getMapData } from '@/lib/mapService';
-import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
+import { ImmichUnavailableError } from '@/lib/immich';
+import { checkRateLimit, getClientIp, retryAfterSeconds } from '@/lib/rate-limit';
 
 export const dynamic = 'force-dynamic';
 
@@ -26,7 +27,7 @@ export async function GET(request: NextRequest) {
       {
         status: 429,
         headers: {
-          'Retry-After': String(Math.ceil((rl.resetAt - Date.now()) / 1000)),
+          'Retry-After': String(retryAfterSeconds(rl.resetAt)),
           'X-RateLimit-Limit': '120',
           'X-RateLimit-Remaining': '0',
         },
@@ -43,7 +44,21 @@ export async function GET(request: NextRequest) {
   const cookieStore = await cookies();
   const getCookie = (name: string) => cookieStore.get(name)?.value;
 
-  const locations = await getMapData();
+  let locations;
+  try {
+    locations = await getMapData();
+  } catch (error) {
+    // Without this the map would render as "no photos anywhere" during an
+    // Immich outage, which is indistinguishable from a gallery with no GPS data.
+    if (error instanceof ImmichUnavailableError) {
+      console.error('[Map API] Immich unavailable:', error.message);
+      return NextResponse.json(
+        { error: 'Immich is currently unavailable' },
+        { status: 503, headers: { 'Retry-After': '30', 'Cache-Control': 'no-store' } },
+      );
+    }
+    throw error;
+  }
 
   // Filter locations and albums based on auth.
   // An album is visible only if BOTH its subpage gate (if any) and its own
diff --git a/app/api/og/route.tsx b/app/api/og/route.tsx
index 7d786a5..ae6d5ad 100644
--- a/app/api/og/route.tsx
+++ b/app/api/og/route.tsx
@@ -9,7 +9,7 @@
 import { ImageResponse } from 'next/og';
 import { NextRequest, NextResponse } from 'next/server';
 import { getConfig } from '@/lib/config';
-import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
+import { checkRateLimit, getClientIp, retryAfterSeconds } from '@/lib/rate-limit';
 
 /**
  * OG image rendering runs satori + resvg per request and each unique ?title
@@ -23,9 +23,15 @@ export async function GET(request: NextRequest) {
   const ip = getClientIp(request);
   const { theme } = getConfig();
 
-  const { success } = checkRateLimit(`og:${ip}`, OG_RPM);
+  const { success, resetAt } = checkRateLimit(`og:${ip}`, OG_RPM);
   if (!success) {
-    return new NextResponse('Too many requests', { status: 429 });
+    return new NextResponse('Too many requests', {
+      status: 429,
+      headers: {
+        'Retry-After': String(retryAfterSeconds(resetAt)),
+        'Cache-Control': 'no-store',
+      },
+    });
   }
 
   const { searchParams } = request.nextUrl;
diff --git a/app/api/video/[id]/route.ts b/app/api/video/[id]/route.ts
index 37118d0..9eafbc1 100644
--- a/app/api/video/[id]/route.ts
+++ b/app/api/video/[id]/route.ts
@@ -10,10 +10,10 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server';
-import { immich } from '@/lib/immich';
+import { immich, ImmichUnavailableError } from '@/lib/immich';
 import { decodeAssetId } from '@/lib/tokens';
 import { getConfig } from '@/lib/config';
-import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
+import { checkRateLimit, getClientIp, retryAfterSeconds } from '@/lib/rate-limit';
 
 export async function GET(request: NextRequest, { params }: { params: Promise<{ id: string }> }) {
   // ── Rate limiting ──────────────────────────────────
@@ -21,9 +21,15 @@ export async function GET(request: NextRequest, { params }: { params: Promise<{
   const { success, remaining, resetAt } = checkRateLimit(`video:${ip}`, getConfig().rateLimitRpm);
 
   if (!success) {
-    const retryAfter = Math.ceil((resetAt - Date.now()) / 1000);
+    const retryAfter = retryAfterSeconds(resetAt);
     console.warn(`[Video API] ⚠️ Rate limit exceeded for IP: ${ip}. Retry after ${retryAfter}s`);
-    return NextResponse.json({ error: 'Too many requests' }, { status: 429 });
+    return NextResponse.json(
+      { error: 'Too many requests' },
+      {
+        status: 429,
+        headers: { 'Retry-After': String(retryAfter), 'Cache-Control': 'no-store' },
+      },
+    );
   }
 
   const { id: token } = await params;
@@ -38,10 +44,28 @@ export async function GET(request: NextRequest, { params }: { params: Promise<{
   // Forward Range header from browser (needed for <video> seeking)
   const rangeHeader = request.headers.get('range');
 
-  const result = await immich.streamVideo(assetId, rangeHeader);
+  let result;
+  try {
+    result = await immich.streamVideo(assetId, rangeHeader);
+  } catch (error) {
+    // Same reasoning as the image route: an outage mid-playback must not be
+    // cached as a permanently missing video.
+    if (error instanceof ImmichUnavailableError) {
+      console.error(`[Video API] Immich unavailable for ${assetId}:`, error.message);
+      return NextResponse.json(
+        { error: 'Immich is currently unavailable' },
+        { status: 503, headers: { 'Retry-After': '30', 'Cache-Control': 'no-store' } },
+      );
+    }
+    throw error;
+  }
+
   if (!result) {
     console.error(`[Video API] ❌ Asset not found in Immich: ${assetId}`);
-    return NextResponse.json({ error: 'Asset not found' }, { status: 404 });
+    return NextResponse.json(
+      { error: 'Asset not found' },
+      { status: 404, headers: { 'Cache-Control': 'no-store' } },
+    );
   }
 
   let contentType = result.contentType.toLowerCase();
diff --git a/app/error.tsx b/app/error.tsx
new file mode 100644
index 0000000..a2b7dd9
--- /dev/null
+++ b/app/error.tsx
@@ -0,0 +1,53 @@
+'use client';
+
+import { useEffect } from 'react';
+import Link from 'next/link';
+
+/**
+ * Rendered when a page throws — in practice almost always
+ * ImmichUnavailableError, since that is what the Immich client raises when the
+ * server cannot answer.
+ *
+ * The wording deliberately does not name Immich or claim to know the cause.
+ * Next.js strips error messages in production builds and replaces them with a
+ * digest, so this component genuinely cannot tell an Immich outage from any
+ * other server error — asserting one would be a guess shown to visitors. The
+ * distinction that matters is already made structurally: notFound() renders
+ * not-found.tsx, a throw renders this.
+ */
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  useEffect(() => {
+    console.error('[Folio] Page render failed:', error);
+  }, [error]);
+
+  return (
+    <div className="empty-state">
+      <h1 className="empty-state__title">Something went wrong</h1>
+      <p className="empty-state__text">
+        This page could not be loaded right now. It is usually temporary — try again in a moment.
+      </p>
+      <div className="empty-state__actions">
+        <button type="button" onClick={reset} className="empty-state__button">
+          Try again
+        </button>
+        <Link href="/" className="empty-state__button empty-state__button--quiet">
+          Back to the gallery
+        </Link>
+      </div>
+      {error.digest && (
+        <p
+          className="empty-state__text"
+          style={{ marginTop: 24, fontSize: '0.8rem', opacity: 0.5 }}
+        >
+          Reference: {error.digest}
+        </p>
+      )}
+    </div>
+  );
+}
diff --git a/app/globals.css b/app/globals.css
index 65af6fe..03a616a 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -1289,6 +1289,55 @@
   font-weight: 300;
 }
 
+.empty-state__title {
+  font-family: var(--font-serif);
+  font-size: clamp(1.75rem, 4vw, 2.5rem);
+  font-weight: 400;
+  letter-spacing: -0.02em;
+  margin-bottom: 12px;
+  color: var(--text-primary);
+}
+
+.empty-state__actions {
+  display: flex;
+  gap: 12px;
+  justify-content: center;
+  flex-wrap: wrap;
+  margin-top: 32px;
+}
+
+/* Matches the PasswordGate button, the only other action button in the app. */
+.empty-state__button {
+  padding: 12px 24px;
+  background: var(--accent);
+  color: var(--bg-primary);
+  border: none;
+  border-radius: var(--radius-md);
+  font-family: var(--font-sans);
+  font-size: 0.85rem;
+  font-weight: 500;
+  letter-spacing: 0.05em;
+  cursor: pointer;
+  text-decoration: none;
+  transition: opacity var(--transition-fast);
+}
+
+.empty-state__button:hover {
+  opacity: 0.9;
+}
+
+.empty-state__button--quiet {
+  background: transparent;
+  color: var(--text-secondary);
+  border: 1px solid var(--border-subtle);
+}
+
+.empty-state__button--quiet:hover {
+  color: var(--text-primary);
+  border-color: var(--border-hover);
+  opacity: 1;
+}
+
 /* ── Theme Conditionals ──────────────────────────── */
 /* Features toggled via data attributes on <html>, set by theme config */
 
diff --git a/app/layout.tsx b/app/layout.tsx
index 0721698..ff78d93 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -13,13 +13,18 @@ import { ThemeToggle } from '@/components/ThemeToggle';
 import { ScrollToTop } from '@/components/ScrollToTop';
 import { Footer } from '@/components/Footer';
 import { SetupScreen } from '@/components/SetupScreen';
-import { getConfig, getGoogleFontsUrl, AppConfig } from '@/lib/config';
+import { getConfigOrNull, getGoogleFontsUrl, AppConfig } from '@/lib/config';
 import { isAdminPath } from '@/lib/admin/paths';
 // DevToolbarLoader is a Client Component (ssr: false is only allowed there)
 import { DevToolbarLoader } from '@/components/DevToolbarLoader';
 
 export async function generateMetadata(): Promise<Metadata> {
-  const config = getConfig();
+  const config = getConfigOrNull();
+  if (!config) {
+    // Nothing to describe, and nothing that should be indexed while broken.
+    return { title: 'Setup Required', robots: { index: false, follow: false } };
+  }
+
   const siteTitle = config.seo.title;
   const siteDescription = config.seo.description;
   const robots = {
@@ -50,7 +55,22 @@ export async function generateMetadata(): Promise<Metadata> {
 }
 
 export default async function RootLayout({ children }: { children: React.ReactNode }) {
-  const config = getConfig();
+  const config = getConfigOrNull();
+  const pathname = (await headers()).get('x-pathname');
+
+  // gallery.yaml exists but cannot be derived — an empty gallery, a nameless
+  // subpage, a subpage with no albums. The admin page builder can write all
+  // three, and this layout is what /admin renders inside, so throwing here
+  // would take down the only tool that can undo the save. Render the minimum
+  // that keeps /admin usable and show everyone else the setup screen.
+  if (!config) {
+    return (
+      <html lang="en" suppressHydrationWarning>
+        <body>{isAdminPath(pathname) ? children : <SetupScreen />}</body>
+      </html>
+    );
+  }
+
   const { theme } = config;
   const fontsUrl = getGoogleFontsUrl(theme);
 
@@ -67,7 +87,6 @@ export default async function RootLayout({ children }: { children: React.ReactNo
 
   // /admin stays reachable during setup — it is the tool that completes the
   // setup, so the setup screen must not lock it out (#326).
-  const pathname = (await headers()).get('x-pathname');
   if ((config as AppConfig & { needsSetup?: boolean }).needsSetup && !isAdminPath(pathname)) {
     return (
       <html lang="en" suppressHydrationWarning>
diff --git a/app/not-found.tsx b/app/not-found.tsx
new file mode 100644
index 0000000..1208244
--- /dev/null
+++ b/app/not-found.tsx
@@ -0,0 +1,26 @@
+import Link from 'next/link';
+
+/**
+ * Rendered when a page calls notFound() — i.e. Immich answered and the album
+ * or asset genuinely does not exist.
+ *
+ * The counterpart is error.tsx, which handles the case where Immich could not
+ * answer at all. Keeping the two apart is the whole point of the
+ * ImmichUnavailableError split: an outage must not tell a visitor (or a
+ * crawler) that their content is gone.
+ */
+export default function NotFound() {
+  return (
+    <div className="empty-state">
+      <h1 className="empty-state__title">Not found</h1>
+      <p className="empty-state__text">
+        This page does not exist, or the album is no longer published.
+      </p>
+      <div className="empty-state__actions">
+        <Link href="/" className="empty-state__button">
+          Back to the gallery
+        </Link>
+      </div>
+    </div>
+  );
+}
diff --git a/lib/__tests__/auth.test.ts b/lib/__tests__/auth.test.ts
index 97963cd..f98e94f 100644
--- a/lib/__tests__/auth.test.ts
+++ b/lib/__tests__/auth.test.ts
@@ -1,4 +1,5 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
+import crypto from 'crypto';
 
 // Mock config to provide a predictable API key and subpage config
 vi.mock('@/lib/config', () => ({
@@ -18,6 +19,15 @@ vi.mock('@/lib/config', () => ({
         albumIds: ['00000000-0000-0000-0000-000000000002'],
         // no password
       },
+      {
+        name: 'Hashed',
+        slug: 'hashed',
+        albumIds: ['00000000-0000-0000-0000-000000000003'],
+        // scrypt hash of 'scrypted-pass' with a fixed salt — exercises the
+        // verifyScrypt path rather than the deprecated plaintext fallback.
+        password:
+          'scrypt:0123456789abcdef0123456789abcdef:4850eef18a09612ef11fdcd943bf64ce98d0eca2b0f677f9c0c51d1f648b8a101cf7ea36b6f94cfc05236b2fda6fffabd0929dc7e14c07626522fba68bf26de5',
+      },
     ],
   }),
 }));
@@ -51,27 +61,64 @@ describe('isProtected', () => {
 });
 
 describe('authenticate', () => {
-  it('returns a Set-Cookie string for the correct password', () => {
-    const cookie = authenticate('private', 'secret123');
+  it('returns a Set-Cookie string for the correct password', async () => {
+    const cookie = await authenticate('private', 'secret123');
     expect(cookie).toBeTruthy();
     expect(cookie).toContain('lb_auth_private=');
     expect(cookie).toContain('HttpOnly');
     expect(cookie).toContain('SameSite=Strict');
   });
 
-  it('returns null for the wrong password', () => {
-    expect(authenticate('private', 'wrongpass')).toBeNull();
+  it('returns null for the wrong password', async () => {
+    await expect(authenticate('private', 'wrongpass')).resolves.toBeNull();
   });
 
-  it('returns null for a non-protected slug', () => {
-    expect(authenticate('public', 'anything')).toBeNull();
+  it('returns null for a non-protected slug', async () => {
+    await expect(authenticate('public', 'anything')).resolves.toBeNull();
+  });
+
+  it('accepts a correct scrypt-hashed password', async () => {
+    await expect(authenticate('hashed', 'scrypted-pass')).resolves.toContain('lb_auth_hashed=');
+  });
+
+  it('rejects a wrong password against a scrypt hash', async () => {
+    await expect(authenticate('hashed', 'wrong')).resolves.toBeNull();
+  });
+});
+
+/**
+ * scryptSync costs ~23ms of blocked main thread per call. The /api/auth limit
+ * is keyed on the client IP, and at the default TRUSTED_PROXY_HOPS=0 that IP
+ * comes from a spoofable header — so unlimited buckets, each buying 23ms of
+ * dead process. The async variant runs on the libuv threadpool instead.
+ */
+describe('password hashing does not stall the process', () => {
+  it('never calls the synchronous scrypt', async () => {
+    const sync = vi.spyOn(crypto, 'scryptSync');
+    await authenticate('hashed', 'scrypted-pass');
+    expect(sync).not.toHaveBeenCalled();
+    sync.mockRestore();
+  });
+
+  it('leaves timers free to fire while hashing', async () => {
+    let ticks = 0;
+    const interval = setInterval(() => ticks++, 2);
+
+    await authenticate('hashed', 'scrypted-pass');
+    clearInterval(interval);
+
+    // The synchronous variant yields to nothing for the whole hash, so a 2ms
+    // interval gets at most one tick after it finishes. Async leaves room for
+    // many. A slower machine makes the hash longer, i.e. more ticks — so this
+    // fails on a blocked loop, not on a busy one.
+    expect(ticks).toBeGreaterThan(3);
   });
 });
 
 describe('isAuthenticated', () => {
-  it('returns true when a valid cookie is present', () => {
+  it('returns true when a valid cookie is present', async () => {
     // First authenticate to get the expected token
-    const cookie = authenticate('private', 'secret123')!;
+    const cookie = (await authenticate('private', 'secret123'))!;
     const token = cookie.split('=')[1].split(';')[0];
 
     const getCookie = (name: string) => (name === 'lb_auth_private' ? token : undefined);
@@ -95,16 +142,16 @@ describe('isAuthenticated', () => {
 });
 
 describe('token expiry', () => {
-  function tokenFor(slug: string, password: string): string {
-    return authenticate(slug, password)!.split('=')[1].split(';')[0];
+  async function tokenFor(slug: string, password: string): Promise<string> {
+    return (await authenticate(slug, password))!.split('=')[1].split(';')[0];
   }
 
   afterEach(() => {
     vi.useRealTimers();
   });
 
-  it('rejects a token once its embedded expiry has passed', () => {
-    const token = tokenFor('private', 'secret123');
+  it('rejects a token once its embedded expiry has passed', async () => {
+    const token = await tokenFor('private', 'secret123');
     const getCookie = (name: string) => (name === 'lb_auth_private' ? token : undefined);
     expect(isAuthenticated('private', getCookie)).toBe(true);
 
@@ -115,8 +162,8 @@ describe('token expiry', () => {
     expect(isAuthenticated('private', getCookie)).toBe(false);
   });
 
-  it('still accepts a token just before it expires', () => {
-    const token = tokenFor('private', 'secret123');
+  it('still accepts a token just before it expires', async () => {
+    const token = await tokenFor('private', 'secret123');
     const getCookie = (name: string) => (name === 'lb_auth_private' ? token : undefined);
 
     vi.useFakeTimers();
@@ -124,8 +171,8 @@ describe('token expiry', () => {
     expect(isAuthenticated('private', getCookie)).toBe(true);
   });
 
-  it('rejects a token whose expiry was tampered with', () => {
-    const token = tokenFor('private', 'secret123');
+  it('rejects a token whose expiry was tampered with', async () => {
+    const token = await tokenFor('private', 'secret123');
     const [, sig] = token.split('.');
     const farFuture = Date.now() + 365 * 24 * 60 * 60 * 1000;
 
@@ -143,8 +190,8 @@ describe('token expiry', () => {
     }
   });
 
-  it('sets a cookie Max-Age consistent with the embedded expiry', () => {
-    const cookie = authenticate('private', 'secret123')!;
+  it('sets a cookie Max-Age consistent with the embedded expiry', async () => {
+    const cookie = (await authenticate('private', 'secret123'))!;
     const maxAge = Number(cookie.match(/Max-Age=(\d+)/)![1]);
     const exp = Number(cookie.split('=')[1].split(';')[0].split('.')[0]);
     expect(Math.abs(exp - (Date.now() + maxAge * 1000))).toBeLessThan(2000);
diff --git a/lib/__tests__/backup-restore.test.ts b/lib/__tests__/backup-restore.test.ts
new file mode 100644
index 0000000..1c70210
--- /dev/null
+++ b/lib/__tests__/backup-restore.test.ts
@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('fs/promises', () => ({
+  default: {
+    copyFile: vi.fn(async () => undefined),
+    readFile: vi.fn(),
+    writeFile: vi.fn(),
+    rename: vi.fn(),
+    mkdir: vi.fn(),
+    access: vi.fn(),
+    readdir: vi.fn(async () => []),
+    unlink: vi.fn(),
+  },
+}));
+
+import fs from 'fs/promises';
+import { restoreBackup } from '@/lib/admin/yaml-service';
+
+/**
+ * restoreBackup joins its argument into a path and copies the result over a
+ * content file, whose contents the admin GET endpoints then return. Before this
+ * guard, `path.join` resolved `..` segments, so any readable file on the host
+ * could be written over content/settings.yaml and read back.
+ *
+ * The function has no callers yet — this pins the guard for whoever wires up the
+ * restore button the admin panel does not have.
+ */
+describe('restoreBackup rejects anything that is not a backup it produced', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  const rejected = [
+    '../../../../etc/passwd',
+    '../gallery.yaml',
+    '.backups/../../gallery.yaml',
+    '/etc/passwd',
+    'gallery.yaml', // the live file, not a backup
+    'gallery.yaml.2026-05-31T17-30-00-000Z.bak.txt',
+    'evil-gallery.yaml.2026-05-31T17-30-00-000Z.bak',
+    '',
+  ];
+
+  for (const name of rejected) {
+    it(`refuses ${JSON.stringify(name)}`, async () => {
+      await expect(restoreBackup(name)).rejects.toThrow(/unrecognised backup name/i);
+      expect(fs.copyFile).not.toHaveBeenCalled();
+    });
+  }
+
+  // A traversal that still ended in a plausible-looking name would have picked
+  // the destination too, via the old includes('gallery.yaml') check.
+  it('refuses a traversal that embeds a valid-looking name', async () => {
+    await expect(restoreBackup('../../gallery.yaml.2026-01-01T00-00-00-000Z.bak')).rejects.toThrow(
+      /unrecognised backup name/i,
+    );
+    expect(fs.copyFile).not.toHaveBeenCalled();
+  });
+});
+
+describe('restoreBackup accepts the names it writes', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('restores a normal backup', async () => {
+    await expect(
+      restoreBackup('gallery.yaml.2026-05-31T17-30-00-000Z.bak'),
+    ).resolves.toBeUndefined();
+    expect(fs.copyFile).toHaveBeenCalled();
+  });
+
+  it('restores a pre-restore backup', async () => {
+    await expect(
+      restoreBackup('settings.yaml.2026-05-31T17-30-00-000Z.pre-restore.bak'),
+    ).resolves.toBeUndefined();
+  });
+
+  it('derives the destination from the matched name, not a substring search', async () => {
+    await restoreBackup('settings.yaml.2026-05-31T17-30-00-000Z.bak');
+
+    // Last copyFile is backup → target; the first is the pre-restore snapshot.
+    const calls = vi.mocked(fs.copyFile).mock.calls;
+    expect(String(calls[calls.length - 1][1])).toMatch(/content\/settings\.yaml$/);
+  });
+});
diff --git a/lib/__tests__/config-hero-uuid.test.ts b/lib/__tests__/config-hero-uuid.test.ts
new file mode 100644
index 0000000..a61d9a4
--- /dev/null
+++ b/lib/__tests__/config-hero-uuid.test.ts
@@ -0,0 +1,93 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('@/lib/env', () => ({
+  env: {
+    IMMICH_API_URL: 'http://localhost:2283',
+    IMMICH_API_KEY: 'test-key',
+    SITE_TITLE: 'Test Gallery',
+    SITE_SUBTITLE: '',
+    CACHE_TTL: 300,
+    IMMICH_TIMEOUT_MS: 15000,
+    RATE_LIMIT_RPM: 120,
+    TRUSTED_PROXY_HOPS: 0,
+  },
+}));
+
+vi.mock('@/lib/secret', () => ({
+  resolveAuthSecret: () => 'test-auth-secret-32-chars-long-min',
+}));
+
+// Spy on validateUuid so we can assert *which* values are routed through it.
+// vi.hoisted because vi.mock factories are hoisted above const declarations.
+// Two-arg signature, matching the real validateUuid(id, context) — the context
+// argument is what the second assertion below inspects.
+const { validateUuidSpy } = vi.hoisted(() => ({
+  validateUuidSpy: vi.fn((id: string, _context: string) => id),
+}));
+
+vi.mock('@/lib/config/parser', () => ({
+  loadYaml: vi.fn(),
+  clearYamlCache: vi.fn(),
+  validateUuid: validateUuidSpy,
+}));
+
+import { getConfig, invalidateConfigCache } from '@/lib/config';
+import { loadYaml } from '@/lib/config/parser';
+
+const ALBUM_ID = '11111111-1111-1111-1111-111111111111';
+const HERO_ID = '22222222-2222-2222-2222-222222222222';
+
+/**
+ * Every asset ID in gallery.yaml is routed through validateUuid before it can
+ * reach encodeAssetId, which encrypts whatever it is handed. A per-album
+ * heroImage was the one that slipped through: the album ID (the map key) was
+ * validated, the hero asset ID (the value) was stored raw. A typo there
+ * produced a perfectly well-formed image URL that 404s forever, with nothing in
+ * the log naming the cause.
+ */
+describe('gallery.yaml per-album heroImage', () => {
+  beforeEach(() => {
+    validateUuidSpy.mockClear();
+    invalidateConfigCache();
+    vi.mocked(loadYaml).mockImplementation((filename: string) => {
+      if (filename === 'gallery.yaml') {
+        return { albums: [{ [ALBUM_ID]: { title: 'An Album', heroImage: HERO_ID } }] };
+      }
+      if (filename === 'settings.yaml') return {};
+      return null;
+    });
+  });
+
+  it('routes the hero asset ID through validateUuid, not just the album ID', () => {
+    getConfig();
+
+    const validated = validateUuidSpy.mock.calls.map((c) => c[0]);
+    expect(validated).toContain(HERO_ID);
+  });
+
+  it('names the album in the validation context so the warning is actionable', () => {
+    getConfig();
+
+    const heroCall = validateUuidSpy.mock.calls.find((c) => c[0] === HERO_ID);
+    expect(heroCall?.[1]).toContain(ALBUM_ID);
+  });
+
+  it('stores the validated value, keyed by album', () => {
+    expect(getConfig().albumHeroImages[ALBUM_ID]).toBe(HERO_ID);
+  });
+
+  // The substitution the wiring above depends on: validateUuid never throws, so
+  // a bad ID degrades to a 404 image rather than taking the whole page down.
+  it('real validateUuid warns and substitutes rather than throwing', async () => {
+    const actual =
+      await vi.importActual<typeof import('@/lib/config/parser')>('@/lib/config/parser');
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    const result = actual.validateUuid('not-a-uuid', 'gallery.yaml heroImage');
+
+    expect(result).toBe('00000000-0000-0000-0000-000000000000');
+    expect(warn).toHaveBeenCalled();
+    expect(String(warn.mock.calls[0][0])).toContain('gallery.yaml heroImage');
+    warn.mockRestore();
+  });
+});
diff --git a/lib/__tests__/config-safe.test.ts b/lib/__tests__/config-safe.test.ts
new file mode 100644
index 0000000..1c42d5c
--- /dev/null
+++ b/lib/__tests__/config-safe.test.ts
@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+vi.mock('@/lib/env', () => ({
+  env: {
+    IMMICH_API_URL: 'http://localhost:2283',
+    IMMICH_API_KEY: 'test-key',
+    SITE_TITLE: 'Test Gallery',
+    SITE_SUBTITLE: '',
+    CACHE_TTL: 300,
+    IMMICH_TIMEOUT_MS: 15000,
+    RATE_LIMIT_RPM: 120,
+    TRUSTED_PROXY_HOPS: 0,
+  },
+}));
+
+vi.mock('@/lib/secret', () => ({
+  resolveAuthSecret: () => 'test-auth-secret-32-chars-long-min',
+}));
+
+vi.mock('@/lib/config/parser', () => ({
+  loadYaml: vi.fn(),
+  clearYamlCache: vi.fn(),
+  validateUuid: (id: string) => id,
+}));
+
+import { getConfig, getConfigOrNull, invalidateConfigCache } from '@/lib/config';
+import { loadYaml } from '@/lib/config/parser';
+
+const ALBUM_ID = '11111111-1111-1111-1111-111111111111';
+
+function withGallery(gallery: unknown) {
+  vi.mocked(loadYaml).mockImplementation((filename: string) => {
+    if (filename === 'gallery.yaml') return gallery;
+    if (filename === 'settings.yaml') return {};
+    return null;
+  });
+}
+
+/**
+ * The admin page builder can write each of these, and the root layout renders
+ * /admin inside itself — so a throw here would take down the site together with
+ * the only tool that can undo the save.
+ */
+const UNDERIVABLE = {
+  'a gallery with neither albums nor subpages': { albums: [] },
+  'a subpage with no name': { albums: [ALBUM_ID], subpages: [{ albums: [ALBUM_ID] }] },
+  'a subpage with neither albums nor sections': {
+    albums: [ALBUM_ID],
+    subpages: [{ name: 'Empty', albums: [] }],
+  },
+};
+
+describe('getConfig() rejects an underivable gallery.yaml', () => {
+  beforeEach(() => invalidateConfigCache());
+
+  // Pins the premise the fix exists for. If these ever stop throwing, the
+  // fallback below is dead weight and should be revisited rather than kept.
+  for (const [label, gallery] of Object.entries(UNDERIVABLE)) {
+    it(`throws on ${label}`, () => {
+      withGallery(gallery);
+      expect(() => getConfig()).toThrow();
+    });
+  }
+});
+
+describe('getConfigOrNull()', () => {
+  let error: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    invalidateConfigCache();
+    error = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => error.mockRestore());
+
+  for (const [label, gallery] of Object.entries(UNDERIVABLE)) {
+    it(`returns null instead of throwing on ${label}`, () => {
+      withGallery(gallery);
+      expect(getConfigOrNull()).toBeNull();
+    });
+  }
+
+  it('logs the underlying error so the cause is diagnosable from the server log', () => {
+    withGallery({ albums: [] });
+    getConfigOrNull();
+
+    expect(error).toHaveBeenCalled();
+    expect(String(error.mock.calls[0][0])).toMatch(/gallery\.yaml/);
+  });
+
+  it('points at the backup directory, since that is the recovery path', () => {
+    withGallery({ albums: [] });
+    getConfigOrNull();
+    expect(String(error.mock.calls[0][0])).toContain('content/.backups/');
+  });
+
+  it('returns the real config untouched when the gallery is valid', () => {
+    withGallery({ albums: [ALBUM_ID] });
+
+    const config = getConfigOrNull();
+    expect(config).not.toBeNull();
+    expect(config?.albums).toEqual([ALBUM_ID]);
+    expect(error).not.toHaveBeenCalled();
+  });
+
+  it('does not swallow the needsSetup path, which is a different state', () => {
+    // Missing gallery.yaml is not an error — getConfig() returns a dummy config
+    // with needsSetup so the app can render SetupScreen. That must still work.
+    vi.mocked(loadYaml).mockReturnValue(null);
+
+    const config = getConfigOrNull();
+    expect(config).not.toBeNull();
+    expect(config?.needsSetup).toBe(true);
+    expect(error).not.toHaveBeenCalled();
+  });
+});
diff --git a/lib/__tests__/derive-gallery.test.ts b/lib/__tests__/derive-gallery.test.ts
new file mode 100644
index 0000000..e59de19
--- /dev/null
+++ b/lib/__tests__/derive-gallery.test.ts
@@ -0,0 +1,106 @@
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('@/lib/env', () => ({
+  env: {
+    IMMICH_API_URL: 'http://localhost:2283',
+    IMMICH_API_KEY: 'test-key',
+    SITE_TITLE: 'Test Gallery',
+    SITE_SUBTITLE: '',
+    CACHE_TTL: 300,
+    IMMICH_TIMEOUT_MS: 15000,
+    RATE_LIMIT_RPM: 120,
+    TRUSTED_PROXY_HOPS: 0,
+  },
+}));
+
+vi.mock('@/lib/config/parser', () => ({
+  loadYaml: vi.fn(),
+  clearYamlCache: vi.fn(),
+  validateUuid: (id: string) => id,
+}));
+
+import { deriveGallery } from '@/lib/config';
+import type { GalleryYaml } from '@/lib/config/schema';
+
+const A = '11111111-1111-1111-1111-111111111111';
+const B = '22222222-2222-2222-2222-222222222222';
+
+/**
+ * The admin PUT calls this before writing, so that a save the site cannot load
+ * is rejected with a 400 instead of reported as successful. These are the exact
+ * shapes the page builder can produce.
+ */
+describe('deriveGallery rejects what the site cannot load', () => {
+  it('rejects a gallery with neither albums nor subpages', () => {
+    expect(() => deriveGallery({ albums: [] } as GalleryYaml)).toThrow(/at least one album/i);
+  });
+
+  it('rejects a subpage with no name', () => {
+    expect(() =>
+      deriveGallery({ albums: [A], subpages: [{ albums: [A] }] } as unknown as GalleryYaml),
+    ).toThrow(/must have a name/i);
+  });
+
+  it('rejects a subpage with neither albums nor sections', () => {
+    expect(() =>
+      deriveGallery({
+        albums: [A],
+        subpages: [{ name: 'Empty', albums: [] }],
+      } as unknown as GalleryYaml),
+    ).toThrow(/Empty/);
+  });
+
+  // The message reaches the admin UI as the 400 body, so it has to identify
+  // which subpage is at fault — "invalid gallery" would be useless in a builder
+  // with a dozen subpages.
+  it('names the offending subpage so the error is actionable', () => {
+    expect(() =>
+      deriveGallery({
+        albums: [A],
+        subpages: [
+          { name: 'Fine', albums: [A] },
+          { name: 'Broken One', albums: [] },
+        ],
+      } as unknown as GalleryYaml),
+    ).toThrow(/Broken One/);
+  });
+});
+
+describe('deriveGallery accepts valid structures', () => {
+  it('derives standalone albums', () => {
+    const result = deriveGallery({ albums: [A, B] } as GalleryYaml);
+    expect(result.albums).toEqual([A, B]);
+    expect(result.standaloneAlbums).toEqual([A, B]);
+    expect(result.subpages).toEqual([]);
+  });
+
+  it('treats an album inside a subpage as no longer standalone', () => {
+    const result = deriveGallery({
+      albums: [A],
+      subpages: [{ name: 'Trips', albums: [B] }],
+    } as unknown as GalleryYaml);
+
+    expect(result.albums).toEqual([A, B]);
+    expect(result.standaloneAlbums).toEqual([A]);
+    expect(result.subpages[0].slug).toBe('trips');
+  });
+
+  it('accepts a subpage that has sections instead of albums', () => {
+    const result = deriveGallery({
+      subpages: [{ name: 'Work', sections: [{ title: 'Recent Work', albums: [A] }] }],
+    } as unknown as GalleryYaml);
+
+    expect(result.subpages[0].sections?.[0].slug).toBe('recent-work');
+    expect(result.albums).toEqual([A]);
+  });
+
+  it('collects per-album overrides and hero images', () => {
+    const result = deriveGallery({
+      albums: [{ [A]: { title: 'Renamed', description: 'A note', heroImage: B } }],
+    } as unknown as GalleryYaml);
+
+    expect(result.albumOverrides[A]).toBe('Renamed');
+    expect(result.albumDescriptions[A]).toBe('A note');
+    expect(result.albumHeroImages[A]).toBe(B);
+  });
+});
diff --git a/lib/__tests__/error-pages.test.ts b/lib/__tests__/error-pages.test.ts
new file mode 100644
index 0000000..dbc2ebe
--- /dev/null
+++ b/lib/__tests__/error-pages.test.ts
@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import NotFound from '@/app/not-found';
+import ErrorPage from '@/app/error';
+
+// Uses createElement rather than JSX because vitest.config.ts only includes
+// lib/__tests__/**/*.test.ts — a .tsx file here would never run.
+
+describe('not-found page', () => {
+  const html = () => renderToStaticMarkup(createElement(NotFound));
+
+  it('uses the themed empty-state styling rather than raw markup', () => {
+    expect(html()).toContain('empty-state');
+  });
+
+  it('offers a way back to the gallery', () => {
+    expect(html()).toContain('href="/"');
+  });
+
+  // notFound() means Immich answered and the content is genuinely gone. If this
+  // page hedged with "try again", a real 404 would look like a transient fault.
+  it('does not suggest the problem is temporary', () => {
+    expect(html()).not.toMatch(/try again|temporar|unavailable/i);
+  });
+});
+
+describe('error page', () => {
+  const render = (error: Error & { digest?: string }) =>
+    renderToStaticMarkup(createElement(ErrorPage, { error, reset: () => {} }));
+
+  it('offers a retry and a way back to the gallery', () => {
+    const html = render(new Error('boom'));
+    expect(html).toContain('Try again');
+    expect(html).toContain('href="/"');
+  });
+
+  it('surfaces the Next.js digest so a report can be traced to a log line', () => {
+    const html = render(Object.assign(new Error('boom'), { digest: 'abc123def' }));
+    expect(html).toContain('abc123def');
+  });
+
+  it('omits the reference line when there is no digest', () => {
+    expect(render(new Error('boom'))).not.toContain('Reference:');
+  });
+
+  // Error messages reaching this component can carry internal detail — an
+  // upstream URL, a header, a config value. Never echo them to a visitor.
+  it('does not leak the raw error message', () => {
+    const html = render(new Error('connect ECONNREFUSED 10.0.0.5:2283 x-api-key=hunter2'));
+    expect(html).not.toContain('hunter2');
+    expect(html).not.toContain('10.0.0.5');
+    expect(html).not.toContain('ECONNREFUSED');
+  });
+
+  // The counterpart assertion to the not-found page: this one *should* frame the
+  // failure as transient, because that is what an Immich outage is.
+  it('frames the failure as temporary', () => {
+    expect(render(new Error('boom'))).toMatch(/temporary/i);
+  });
+});
diff --git a/lib/__tests__/image-cache-version.test.ts b/lib/__tests__/image-cache-version.test.ts
new file mode 100644
index 0000000..495371c
--- /dev/null
+++ b/lib/__tests__/image-cache-version.test.ts
@@ -0,0 +1,78 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('@/lib/config', () => ({
+  getConfig: () => ({ authSecret: 'test-auth-secret-32-chars-long-min' }),
+}));
+
+const ASSET = '11111111-1111-1111-1111-111111111111';
+
+/**
+ * Image responses are served `immutable` for a year, so the browser never
+ * revalidates — the ETag is not even consulted. The URL is the only thing that
+ * can invalidate a browser cache, which is why the buster lives there and not
+ * only in the ETag. Immich regenerates thumbnails when a job is re-run or a
+ * photo is rotated, and the asset ID does not change, so nothing else would.
+ */
+describe('IMAGE_CACHE_VERSION', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.unstubAllEnvs();
+  });
+
+  async function urls() {
+    const { imageUrl, videoUrl } = await import('@/lib/urls');
+    return { imageUrl, videoUrl };
+  }
+
+  it('leaves URLs byte-identical when unset — the default must not change', async () => {
+    const { imageUrl, videoUrl } = await urls();
+
+    expect(imageUrl(ASSET)).toMatch(/^\/api\/image\/[^?]+\?size=preview$/);
+    expect(imageUrl(ASSET, 'thumbnail')).toMatch(/^\/api\/image\/[^?]+\?size=thumbnail$/);
+    expect(videoUrl(ASSET)).toMatch(/^\/api\/video\/[^?]+$/);
+  });
+
+  it('treats an empty or whitespace-only value as unset', async () => {
+    vi.stubEnv('IMAGE_CACHE_VERSION', '   ');
+    const { imageUrl } = await urls();
+    expect(imageUrl(ASSET)).not.toContain('v=');
+  });
+
+  it('appends the version to image URLs when set', async () => {
+    vi.stubEnv('IMAGE_CACHE_VERSION', '2');
+    const { imageUrl } = await urls();
+    expect(imageUrl(ASSET)).toMatch(/\?size=preview&v=2$/);
+  });
+
+  it('uses a leading ? on video URLs, which carry no other parameter', async () => {
+    vi.stubEnv('IMAGE_CACHE_VERSION', '2');
+    const { videoUrl } = await urls();
+
+    const url = videoUrl(ASSET);
+    expect(url).toMatch(/\?v=2$/);
+    expect(url).not.toContain('?&');
+  });
+
+  it('escapes a value that would otherwise break the query string', async () => {
+    vi.stubEnv('IMAGE_CACHE_VERSION', 'a b&c=d');
+    const { imageUrl } = await urls();
+
+    const url = imageUrl(ASSET);
+    expect(url).toContain('v=a%20b%26c%3Dd');
+    // One '&' only — the separator. An unescaped value would inject parameters.
+    expect(url.split('&')).toHaveLength(2);
+  });
+
+  it('changes the URL when bumped, which is the entire point', async () => {
+    vi.stubEnv('IMAGE_CACHE_VERSION', '1');
+    const before = (await urls()).imageUrl(ASSET);
+
+    vi.resetModules();
+    vi.stubEnv('IMAGE_CACHE_VERSION', '2');
+    const after = (await urls()).imageUrl(ASSET);
+
+    expect(after).not.toBe(before);
+    // The token itself is unchanged: same asset, same encryption, new cache key.
+    expect(after.split('?')[0]).toBe(before.split('?')[0]);
+  });
+});
diff --git a/lib/__tests__/image-size.test.ts b/lib/__tests__/image-size.test.ts
new file mode 100644
index 0000000..c5d43ca
--- /dev/null
+++ b/lib/__tests__/image-size.test.ts
@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { resolveImageSize, widthToSize } from '../imageSize';
+
+describe('widthToSize', () => {
+  it('maps widths to Immich tiers at the documented boundaries', () => {
+    expect(widthToSize(250)).toBe('thumbnail');
+    expect(widthToSize(251)).toBe('preview');
+    expect(widthToSize(1440)).toBe('preview');
+    expect(widthToSize(1441)).toBe('original');
+  });
+});
+
+describe('resolveImageSize', () => {
+  it('defaults to preview when neither parameter is given', () => {
+    expect(resolveImageSize(null, null)).toBe('preview');
+  });
+
+  it('honours an explicit size on its own', () => {
+    expect(resolveImageSize('thumbnail', null)).toBe('thumbnail');
+    expect(resolveImageSize('original', null)).toBe('original');
+  });
+
+  it('falls back to the width-derived tier when no size is given', () => {
+    expect(resolveImageSize(null, '128')).toBe('thumbnail');
+    expect(resolveImageSize(null, '3840')).toBe('original');
+  });
+
+  it('ignores an unrecognised size rather than trusting it', () => {
+    expect(resolveImageSize('enormous', null)).toBe('preview');
+  });
+
+  it('ignores a non-numeric or non-positive width', () => {
+    expect(resolveImageSize('preview', 'abc')).toBe('preview');
+    expect(resolveImageSize('preview', '0')).toBe('preview');
+    expect(resolveImageSize('preview', '-100')).toBe('preview');
+  });
+
+  // The reason this function exists. ?size= is a ceiling; a width may lower the
+  // tier but must never raise it.
+  describe('when both are present, the smaller tier wins', () => {
+    it('lets a small width narrow the requested size', () => {
+      expect(resolveImageSize('preview', '128')).toBe('thumbnail');
+    });
+
+    // The regression this guards. next/image emits widths up to 3840 and
+    // widthToSize(1920) is 'original' — letting width win would ship full-size
+    // originals to every large display.
+    it('never upgrades past the requested size', () => {
+      expect(resolveImageSize('preview', '1920')).toBe('preview');
+      expect(resolveImageSize('preview', '3840')).toBe('preview');
+      expect(resolveImageSize('thumbnail', '3840')).toBe('thumbnail');
+    });
+
+    it('leaves the real grid case unchanged', () => {
+      // lib/urls.ts writes ?size=preview; next/image's smallest vw-based
+      // deviceSize is 640. This combination must stay on preview.
+      expect(resolveImageSize('preview', '640')).toBe('preview');
+    });
+  });
+});
diff --git a/lib/__tests__/immich.test.ts b/lib/__tests__/immich.test.ts
index e36844e..4db7466 100644
--- a/lib/__tests__/immich.test.ts
+++ b/lib/__tests__/immich.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { immich } from '../immich';
+import { immich, ImmichUnavailableError } from '../immich';
 import * as config from '../config';
 import { cache } from '../cache';
 
@@ -16,7 +16,11 @@ vi.mock('../config', async () => {
       subpages: [],
       albumOverrides: { 'album-1': 'Override Name' },
       albumDescriptions: {},
-      cacheTtl: 0,
+      // Non-zero: a 0 TTL expires an entry in the same millisecond it is
+      // written, which would make any caching assertion flaky. Isolation comes
+      // from the cache.clear() in beforeEach, not from an unusable TTL.
+      cacheTtl: 60_000,
+      immichTimeoutMs: 15000,
     }),
   };
 });
@@ -57,6 +61,294 @@ describe('ImmichClient', () => {
       const result = await (immich as any).request('/test');
       expect(result).toBeNull();
     });
+
+    // A null return means "Immich answered: this does not exist" and the page
+    // turns it into notFound(). Every other failure must be distinguishable,
+    // or an outage renders a hard 404 for albums that do exist.
+    describe('distinguishes "gone" from "unavailable"', () => {
+      it('returns null for 410 Gone', async () => {
+        mockFetch.mockResolvedValueOnce({ ok: false, status: 410, statusText: 'Gone' });
+        await expect((immich as any).request('/test')).resolves.toBeNull();
+      });
+
+      it('throws on a 5xx instead of reporting the resource as missing', async () => {
+        mockFetch.mockResolvedValueOnce({
+          ok: false,
+          status: 503,
+          statusText: 'Service Unavailable',
+        });
+
+        await expect((immich as any).request('/test')).rejects.toBeInstanceOf(
+          ImmichUnavailableError,
+        );
+      });
+
+      it('throws on a rejected API key rather than 404-ing every album', async () => {
+        mockFetch.mockResolvedValueOnce({ ok: false, status: 401, statusText: 'Unauthorized' });
+        await expect((immich as any).request('/test')).rejects.toBeInstanceOf(
+          ImmichUnavailableError,
+        );
+      });
+
+      it('throws when the network is unreachable', async () => {
+        mockFetch.mockRejectedValueOnce(new Error('ECONNREFUSED'));
+        await expect((immich as any).request('/test')).rejects.toBeInstanceOf(
+          ImmichUnavailableError,
+        );
+      });
+
+      it('throws when a gateway returns an HTML error page instead of JSON', async () => {
+        mockFetch.mockResolvedValueOnce({
+          ok: true,
+          headers: { get: () => 'text/html' },
+          json: async () => ({}),
+        });
+
+        await expect((immich as any).request('/test')).rejects.toBeInstanceOf(
+          ImmichUnavailableError,
+        );
+      });
+
+      it('carries the upstream status for logging', async () => {
+        mockFetch.mockResolvedValueOnce({ ok: false, status: 502, statusText: 'Bad Gateway' });
+        await expect((immich as any).request('/test')).rejects.toMatchObject({ status: 502 });
+      });
+    });
+  });
+
+  // Without a budget the only ceiling is undici's default, measured in minutes.
+  // Every page is force-dynamic, so an Immich that accepts connections but never
+  // answers would hold each visitor's render open for that whole window.
+  describe('timeouts', () => {
+    const timeoutError = () => {
+      const err = new Error('The operation was aborted due to timeout');
+      err.name = 'TimeoutError';
+      return err;
+    };
+
+    it('sends an abort signal with every JSON request', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        headers: { get: () => 'application/json' },
+        json: async () => ({}),
+      });
+
+      await (immich as any).request('/test');
+      expect(mockFetch.mock.calls[0][1].signal).toBeInstanceOf(AbortSignal);
+    });
+
+    it('reports a timed-out request as unavailable, not as a missing resource', async () => {
+      mockFetch.mockRejectedValueOnce(timeoutError());
+
+      await expect((immich as any).request('/test')).rejects.toBeInstanceOf(ImmichUnavailableError);
+    });
+
+    it('names the budget in the error so a misconfigured timeout is diagnosable', async () => {
+      mockFetch.mockRejectedValueOnce(timeoutError());
+      await expect((immich as any).request('/test')).rejects.toThrow(/15000ms/);
+    });
+
+    // The stream methods deliberately use a headers-only timeout. A whole-request
+    // timeout would truncate a large original photo or a long video mid-transfer.
+    it('stops the clock once stream headers arrive, so a slow body is not truncated', async () => {
+      vi.useFakeTimers();
+      try {
+        let captured: AbortSignal | undefined;
+        mockFetch.mockImplementation(async (_url: string, init: { signal?: AbortSignal }) => {
+          captured = init.signal;
+          return {
+            ok: true,
+            status: 200,
+            body: new ReadableStream(),
+            headers: { get: () => null },
+          };
+        });
+
+        const result = await immich.streamAsset('asset-1');
+        expect(result).not.toBeNull();
+
+        // Far beyond the 15s budget: a whole-request timeout would abort here
+        // and kill an in-progress download.
+        vi.advanceTimersByTime(60 * 60 * 1000);
+        expect(captured?.aborted).toBe(false);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it('still aborts a stream that never returns headers', async () => {
+      vi.useFakeTimers();
+      try {
+        let captured: AbortSignal | undefined;
+        mockFetch.mockImplementation(
+          (_url: string, init: { signal?: AbortSignal }) =>
+            new Promise((_resolve, reject) => {
+              captured = init.signal;
+              init.signal?.addEventListener('abort', () => reject(timeoutError()));
+            }),
+        );
+
+        const pending = immich.streamAsset('asset-1');
+        // Attach the rejection handler *before* advancing timers: the abort
+        // fires during advanceTimersByTimeAsync, and a promise that rejects
+        // with no handler yet attached is reported as an unhandled rejection,
+        // which fails the whole vitest run.
+        const rejects = expect(pending).rejects.toBeInstanceOf(ImmichUnavailableError);
+        await vi.advanceTimersByTimeAsync(15001);
+
+        await rejects;
+        expect(captured?.aborted).toBe(true);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+  });
+
+  // The image/video routes serve these URLs with `immutable` on success and turn
+  // a null into a 404. A bare 404 is heuristically cacheable, so an outage that
+  // looked like "missing" could pin a broken image in the browser cache.
+  describe('stream failures distinguish gone from unavailable', () => {
+    const streamRes = (status: number) => ({
+      ok: status >= 200 && status < 300,
+      status,
+      body: null,
+      headers: { get: () => null },
+    });
+
+    it('streamAsset returns null for a genuinely missing asset', async () => {
+      mockFetch.mockResolvedValueOnce(streamRes(404));
+      await expect(immich.streamAsset('asset-1')).resolves.toBeNull();
+    });
+
+    it('streamAsset throws when Immich errors rather than reporting it missing', async () => {
+      mockFetch.mockResolvedValueOnce(streamRes(500));
+      await expect(immich.streamAsset('asset-1')).rejects.toBeInstanceOf(ImmichUnavailableError);
+    });
+
+    it('streamAsset throws when the network is unreachable', async () => {
+      mockFetch.mockRejectedValueOnce(new Error('ECONNREFUSED'));
+      await expect(immich.streamAsset('asset-1')).rejects.toBeInstanceOf(ImmichUnavailableError);
+    });
+
+    it('streamAsset throws on a 200 with no body', async () => {
+      mockFetch.mockResolvedValueOnce(streamRes(200));
+      await expect(immich.streamAsset('asset-1')).rejects.toBeInstanceOf(ImmichUnavailableError);
+    });
+
+    it('streamVideo returns null for a genuinely missing video', async () => {
+      mockFetch.mockResolvedValueOnce(streamRes(404));
+      await expect(immich.streamVideo('asset-1')).resolves.toBeNull();
+    });
+
+    it('streamVideo throws when Immich errors', async () => {
+      mockFetch.mockResolvedValueOnce(streamRes(502));
+      await expect(immich.streamVideo('asset-1')).rejects.toBeInstanceOf(ImmichUnavailableError);
+    });
+
+    it('streamVideo still accepts a 206 partial response for seeking', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        status: 206,
+        body: new ReadableStream(),
+        headers: { get: () => null },
+      });
+
+      const result = await immich.streamVideo('asset-1', 'bytes=0-1023');
+      expect(result?.status).toBe(206);
+    });
+  });
+
+  // Measured before the fix: 5 sequential lookups of a missing asset produced 5
+  // upstream fetches. The homepage resolves every gallery.yaml hero ID on each
+  // render and is force-dynamic, so a hero photo deleted from Immich cost one
+  // 404 round-trip per page view, indefinitely.
+  describe('negative caching', () => {
+    const notFound = { ok: false, status: 404, statusText: 'Not Found' };
+
+    it('queries Immich once for a repeatedly-requested missing asset', async () => {
+      mockFetch.mockResolvedValue(notFound);
+
+      for (let i = 0; i < 5; i++) {
+        await expect(immich.getAssetInfo('missing-asset')).resolves.toBeNull();
+      }
+
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    it('queries Immich once for a repeatedly-requested missing album', async () => {
+      mockFetch.mockResolvedValue(notFound);
+
+      for (let i = 0; i < 3; i++) {
+        await expect(immich.getAlbum('album-1')).resolves.toBeNull();
+      }
+
+      // One album request + one metadata-search request, from the first call only.
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not cache an outage, which would outlive the recovery', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: false, status: 503, statusText: 'Unavailable' });
+      await expect(immich.getAssetInfo('asset-1')).rejects.toBeInstanceOf(ImmichUnavailableError);
+
+      // Immich recovers: the very next call must reach it, not replay the failure.
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        headers: { get: () => 'application/json' },
+        json: async () => ({ id: 'asset-1' }),
+      });
+
+      await expect(immich.getAssetInfo('asset-1')).resolves.toMatchObject({ id: 'asset-1' });
+    });
+
+    it('a cached absence is cleared by invalidation, so a fix takes effect at once', async () => {
+      mockFetch.mockResolvedValue(notFound);
+      await expect(immich.getAssetInfo('asset-1')).resolves.toBeNull();
+
+      immich.invalidateAll();
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        headers: { get: () => 'application/json' },
+        json: async () => ({ id: 'asset-1' }),
+      });
+
+      await expect(immich.getAssetInfo('asset-1')).resolves.toMatchObject({ id: 'asset-1' });
+    });
+  });
+
+  // The regression this whole error type exists to prevent.
+  describe('outage handling', () => {
+    it('getAlbum propagates an outage instead of returning null', async () => {
+      // Not mockResolvedValueOnce: getAlbum fires the album and metadata-search
+      // requests concurrently, so both need the failing response.
+      mockFetch.mockResolvedValue({ ok: false, status: 500, statusText: 'Internal Server Error' });
+
+      await expect(immich.getAlbum('album-1')).rejects.toBeInstanceOf(ImmichUnavailableError);
+    });
+
+    it('getAlbums propagates an outage instead of returning an empty list', async () => {
+      // Returning [] here would render the homepage as "this gallery has no
+      // albums" while Immich is merely down.
+      mockFetch.mockResolvedValue({ ok: false, status: 500, statusText: 'Internal Server Error' });
+
+      await expect(immich.getAlbums()).rejects.toBeInstanceOf(ImmichUnavailableError);
+    });
+
+    it('a failed album does not leave a stale entry in the in-flight map', async () => {
+      mockFetch.mockResolvedValue({ ok: false, status: 500, statusText: 'Internal Server Error' });
+      await expect(immich.getAlbum('album-1')).rejects.toBeInstanceOf(ImmichUnavailableError);
+
+      // A stranded pending promise would make every later call replay the
+      // failure forever, even after Immich recovers.
+      expect((immich as any).pendingAlbumPromises.has('album-1')).toBe(false);
+      expect((immich as any).pendingAlbumsPromise).toBeNull();
+    });
+
+    it('ping reports unreachable as false rather than throwing', async () => {
+      // /api/health and /api/admin/status render this as a status field.
+      mockFetch.mockRejectedValueOnce(new Error('ECONNREFUSED'));
+      await expect(immich.ping()).resolves.toBe(false);
+    });
   });
 
   describe('getAlbums()', () => {
diff --git a/lib/__tests__/proxy.test.ts b/lib/__tests__/proxy.test.ts
new file mode 100644
index 0000000..c2378df
--- /dev/null
+++ b/lib/__tests__/proxy.test.ts
@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import { NextRequest } from 'next/server';
+import { proxy, config } from '@/proxy';
+
+// Next.js 16 renamed the "middleware" file convention to "proxy": the file must
+// be proxy.ts and must export proxy(), not middleware(). A silent regression here
+// (wrong filename, wrong export name) means Next.js never invokes this code and
+// every document response ships without a CSP — with no build error to catch it.
+describe('proxy', () => {
+  const run = (pathname = '/') => proxy(new NextRequest(`https://example.com${pathname}`));
+
+  it('is exported under the name Next.js 16 expects', () => {
+    expect(typeof proxy).toBe('function');
+  });
+
+  it('sets a Content-Security-Policy on the response', () => {
+    const csp = run().headers.get('Content-Security-Policy');
+    expect(csp).toContain("default-src 'self'");
+    expect(csp).toContain("frame-ancestors 'none'");
+  });
+
+  it('issues a per-request nonce and passes it to pages via x-nonce', () => {
+    const response = run();
+    const nonce = response.headers.get('x-middleware-request-x-nonce');
+    expect(nonce).toBeTruthy();
+    // The nonce in the CSP must be the same one the page receives, otherwise
+    // Next.js stamps scripts with a nonce the policy does not allow.
+    expect(response.headers.get('Content-Security-Policy')).toContain(`'nonce-${nonce}'`);
+  });
+
+  it('generates a different nonce per request', () => {
+    const first = run().headers.get('x-middleware-request-x-nonce');
+    const second = run().headers.get('x-middleware-request-x-nonce');
+    expect(first).not.toBe(second);
+  });
+
+  it('forwards the pathname so the root layout can keep /admin reachable', () => {
+    const response = run('/admin/settings');
+    expect(response.headers.get('x-middleware-request-x-pathname')).toBe('/admin/settings');
+  });
+
+  it('does not set unsafe-inline alongside the nonce', () => {
+    // CSP2-only browsers ignore 'strict-dynamic' and would honour the fallback,
+    // making it strictly worse than having none.
+    expect(run().headers.get('Content-Security-Policy')).not.toContain(
+      "script-src 'self' 'unsafe-inline'",
+    );
+  });
+
+  it('keeps a matcher that excludes api and static assets but covers /admin', () => {
+    const source = config.matcher[0].source;
+    expect(source).toContain('api');
+    expect(source).toContain('_next/static');
+    expect(source).not.toContain('admin');
+  });
+});
diff --git a/lib/__tests__/rate-limit.test.ts b/lib/__tests__/rate-limit.test.ts
index fc4d976..ab23e06 100644
--- a/lib/__tests__/rate-limit.test.ts
+++ b/lib/__tests__/rate-limit.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { NextRequest } from 'next/server';
 
 let mockHops = 0;
@@ -6,7 +6,12 @@ vi.mock('@/lib/config', () => ({
   getConfig: () => ({ trustedProxyHops: mockHops }),
 }));
 
-import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
+import {
+  checkRateLimit,
+  getClientIp,
+  retryAfterSeconds,
+  __resetProxyWarningForTests,
+} from '@/lib/rate-limit';
 
 function req(headers: Record<string, string>, ip?: string): NextRequest {
   return { ...(ip ? { ip } : {}), headers: new Headers(headers) } as unknown as NextRequest;
@@ -85,6 +90,86 @@ describe('getClientIp behind two trusted proxies (TRUSTED_PROXY_HOPS=2)', () =>
   });
 });
 
+/**
+ * Falling back to the shared 'unknown' bucket is correct — trusting a spoofable
+ * header would be worse — but silent. Every unidentified request shares one
+ * bucket per endpoint, and a 50-photo grid issues ~50 /api/image requests, so
+ * the default 1500 rpm is collectively spent by ~30 page loads a minute.
+ * Visitors get 429s with nothing in the log naming the cause.
+ */
+describe('diagnosing an unidentifiable client', () => {
+  let warn: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    __resetProxyWarningForTests();
+    warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  // Without this the spies stack on console.warn across tests and call counts
+  // accumulate, which silently turns every assertion below into a false pass
+  // or a confusing failure.
+  afterEach(() => warn.mockRestore());
+
+  it('warns when the forwarded chain is shorter than the configured hops', () => {
+    mockHops = 2;
+    expect(getClientIp(req({ 'x-forwarded-for': '203.0.113.9' }))).toBe('unknown');
+
+    expect(warn).toHaveBeenCalledOnce();
+    const message = String(warn.mock.calls[0][0]);
+    expect(message).toContain('TRUSTED_PROXY_HOPS is 2');
+    expect(message).toContain('1 entry');
+  });
+
+  it('warns when neither forwarding header is present', () => {
+    mockHops = 1;
+    expect(getClientIp(req({}))).toBe('unknown');
+    expect(String(warn.mock.calls[0][0])).toContain('neither X-Forwarded-For nor X-Real-IP');
+  });
+
+  it('explains why X-Real-IP was not trusted at more than one hop', () => {
+    mockHops = 2;
+    expect(getClientIp(req({ 'x-real-ip': '203.0.113.9' }))).toBe('unknown');
+    expect(String(warn.mock.calls[0][0])).toContain('single hop');
+  });
+
+  it('warns once per process, not once per request', () => {
+    mockHops = 2;
+    for (let i = 0; i < 50; i++) getClientIp(req({}));
+    expect(warn).toHaveBeenCalledOnce();
+  });
+
+  it('stays silent while clients are being identified correctly', () => {
+    mockHops = 1;
+    expect(getClientIp(req({ 'x-forwarded-for': '203.0.113.9' }))).toBe('203.0.113.9');
+    expect(getClientIp(req({ 'x-real-ip': '203.0.113.9' }))).toBe('203.0.113.9');
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('stays silent at hops=0, where the shared bucket is expected, not a misconfiguration', () => {
+    mockHops = 0;
+    expect(getClientIp(req({}))).toBe('unknown');
+    expect(warn).not.toHaveBeenCalled();
+  });
+});
+
+describe('retryAfterSeconds', () => {
+  it('rounds up, so a client never retries before the window closes', () => {
+    expect(retryAfterSeconds(Date.now() + 1500)).toBe(2);
+    expect(retryAfterSeconds(Date.now() + 30_000)).toBe(30);
+  });
+
+  // The reason this is a function rather than an inline Math.ceil. Every route
+  // had its own copy, and each shared this edge: a window on the point of
+  // expiring gives 0, and `Retry-After: 0` tells the client to retry at once —
+  // the opposite of what a 429 means. A past resetAt gives a negative number,
+  // which is not valid HTTP at all.
+  it('never returns zero or a negative value', () => {
+    expect(retryAfterSeconds(Date.now())).toBe(1);
+    expect(retryAfterSeconds(Date.now() + 10)).toBe(1);
+    expect(retryAfterSeconds(Date.now() - 60_000)).toBe(1);
+  });
+});
+
 describe('checkRateLimit', () => {
   // Use unique IP prefixes per test to avoid cross-contamination
   let testIp: string;
diff --git a/lib/__tests__/yaml-write.test.ts b/lib/__tests__/yaml-write.test.ts
new file mode 100644
index 0000000..4d1aad0
--- /dev/null
+++ b/lib/__tests__/yaml-write.test.ts
@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('fs/promises', () => ({
+  default: {
+    mkdir: vi.fn(async () => undefined),
+    access: vi.fn(async () => {
+      throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    }),
+    copyFile: vi.fn(async () => undefined),
+    readdir: vi.fn(async () => []),
+    unlink: vi.fn(async () => undefined),
+    writeFile: vi.fn(async () => undefined),
+    rename: vi.fn(async () => undefined),
+    readFile: vi.fn(),
+  },
+}));
+
+import fs from 'fs/promises';
+import { writeGalleryYaml } from '@/lib/admin/yaml-service';
+
+const gallery = { albums: ['11111111-1111-1111-1111-111111111111'] };
+
+const tmpPaths = () => vi.mocked(fs.writeFile).mock.calls.map((c) => String(c[0]));
+
+/**
+ * The rename is what makes the write atomic; the temp filename is what did not
+ * used to be. With a constant `gallery.yaml.tmp`, two saves in flight at once
+ * shared it, so the second writeFile could interleave with the first's rename.
+ */
+describe('writeYamlFile temp file handling', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('never writes to the bare .tmp path two callers would collide on', async () => {
+    await writeGalleryYaml(gallery);
+    expect(tmpPaths()[0]).not.toMatch(/gallery\.yaml\.tmp$/);
+  });
+
+  it('uses a distinct temp path for every write', async () => {
+    await writeGalleryYaml(gallery);
+    await writeGalleryYaml(gallery);
+    await writeGalleryYaml(gallery);
+
+    const paths = tmpPaths();
+    expect(paths).toHaveLength(3);
+    expect(new Set(paths).size).toBe(3);
+  });
+
+  it('renames the temp file it just wrote, not some other one', async () => {
+    await writeGalleryYaml(gallery);
+
+    const [written] = tmpPaths();
+    const [from, to] = vi.mocked(fs.rename).mock.calls[0].map(String);
+    expect(from).toBe(written);
+    expect(to).toMatch(/content\/gallery\.yaml$/);
+  });
+
+  it('cleans up the temp file when the write fails', async () => {
+    vi.mocked(fs.writeFile).mockRejectedValueOnce(new Error('ENOSPC'));
+
+    await expect(writeGalleryYaml(gallery)).rejects.toThrow('ENOSPC');
+    expect(String(vi.mocked(fs.unlink).mock.calls[0][0])).toBe(tmpPaths()[0]);
+  });
+
+  it('cleans up when the rename fails', async () => {
+    vi.mocked(fs.rename).mockRejectedValueOnce(new Error('EXDEV'));
+
+    await expect(writeGalleryYaml(gallery)).rejects.toThrow('EXDEV');
+    expect(fs.unlink).toHaveBeenCalledOnce();
+  });
+
+  it('does not let a cleanup failure mask the real error', async () => {
+    vi.mocked(fs.writeFile).mockRejectedValueOnce(new Error('ENOSPC'));
+    vi.mocked(fs.unlink).mockRejectedValueOnce(new Error('EACCES'));
+
+    await expect(writeGalleryYaml(gallery)).rejects.toThrow('ENOSPC');
+  });
+
+  it('does not unlink on the happy path', async () => {
+    await writeGalleryYaml(gallery);
+    expect(fs.unlink).not.toHaveBeenCalled();
+  });
+});
diff --git a/lib/admin/paths.ts b/lib/admin/paths.ts
index 626cdc6..a7cf193 100644
--- a/lib/admin/paths.ts
+++ b/lib/admin/paths.ts
@@ -4,7 +4,7 @@
  * Used by the root layout to keep /admin reachable while the app is in
  * setup mode: the setup screen must not lock out the very tool that fixes
  * an incomplete configuration (#326). A null pathname (header missing,
- * e.g. a route not covered by the middleware matcher) counts as non-admin
+ * e.g. a route not covered by the proxy matcher) counts as non-admin
  * so the setup screen remains the safe default.
  */
 export function isAdminPath(pathname: string | null): boolean {
diff --git a/lib/admin/yaml-service.ts b/lib/admin/yaml-service.ts
index 5603def..8c30d9a 100644
--- a/lib/admin/yaml-service.ts
+++ b/lib/admin/yaml-service.ts
@@ -11,6 +11,9 @@ import type { GalleryYaml, SettingsYaml } from '../config/schema';
 const CONTENT_DIR = path.join(process.cwd(), 'content');
 const MAX_BACKUPS = 10; // Keep last 10 backups per file
 
+/** Disambiguates temp files within one process; the pid covers across them. */
+let tmpCounter = 0;
+
 /** Read gallery.yaml and return parsed content. */
 export async function readGalleryYaml(): Promise<GalleryYaml | null> {
   try {
@@ -71,10 +74,23 @@ async function writeYamlFile(filename: string, data: unknown): Promise<void> {
       sortKeys: false,
     });
 
-  // Atomic write: write to temp file, then rename
-  const tmpPath = `${filePath}.tmp`;
-  await fs.writeFile(tmpPath, content, 'utf8');
-  await fs.rename(tmpPath, filePath);
+  // Atomic write: write to a *unique* temp file, then rename.
+  //
+  // The rename is what makes this atomic; the temp filename is what did not.
+  // With a constant `${filePath}.tmp`, two saves of the same file in flight at
+  // once shared it — the second writeFile could interleave with the first's
+  // rename, leaving one save's bytes published under the other's, or a
+  // truncated mix. A double-clicked Save in the page builder is enough.
+  const tmpPath = `${filePath}.${process.pid}.${++tmpCounter}.tmp`;
+  try {
+    await fs.writeFile(tmpPath, content, 'utf8');
+    await fs.rename(tmpPath, filePath);
+  } catch (err) {
+    // Do not leave litter in content/ behind a failed save. Cleanup failure is
+    // not worth masking the real error with.
+    await fs.unlink(tmpPath).catch(() => {});
+    throw err;
+  }
 
   console.log(`[Admin] ✅ Saved ${filename}`);
 }
@@ -103,16 +119,32 @@ export async function listBackups(filename: string): Promise<string[]> {
   }
 }
 
+/**
+ * Names this service actually produces, and the only ones it will restore from.
+ *
+ * `[\w-]` matches neither `/` nor `.`, and the anchors leave no room for a
+ * prefix, so a `..` segment cannot match. Without this, `path.join` happily
+ * resolves `../../../../etc/passwd` and the copy below writes an arbitrary
+ * readable file over content/settings.yaml — which the admin GET endpoints then
+ * hand straight back.
+ */
+const BACKUP_FILENAME = /^(gallery|settings)\.yaml\.[\w-]+\.(pre-restore\.)?bak$/;
+
 /** Restore a specific backup. */
 export async function restoreBackup(backupFilename: string): Promise<void> {
+  const match = BACKUP_FILENAME.exec(backupFilename);
+  // The basename check is redundant against the regex above, and kept
+  // deliberately: it keeps the guarantee if that pattern is ever loosened.
+  if (!match || path.basename(backupFilename) !== backupFilename) {
+    throw new Error(`Refusing to restore from an unrecognised backup name: "${backupFilename}"`);
+  }
+
   const backupDir = path.join(CONTENT_DIR, '.backups');
   const backupPath = path.join(backupDir, backupFilename);
 
-  // Determine the original filename
-  const originalFilename = backupFilename.includes('gallery.yaml')
-    ? 'gallery.yaml'
-    : 'settings.yaml';
-
+  // Derived from the matched group, never from a substring search on the input:
+  // `includes('gallery.yaml')` would let the caller pick the destination.
+  const originalFilename = `${match[1]}.yaml`;
   const targetPath = path.join(CONTENT_DIR, originalFilename);
 
   // Create a backup of current state first
diff --git a/lib/auth.ts b/lib/auth.ts
index c49f381..c66c465 100644
--- a/lib/auth.ts
+++ b/lib/auth.ts
@@ -18,15 +18,35 @@ function isBcryptHash(str: string): boolean {
   return str.startsWith('$2a$') || str.startsWith('$2b$') || str.startsWith('$2y$');
 }
 
+/**
+ * scrypt on the libuv threadpool rather than the main thread.
+ *
+ * scryptSync costs ~23ms per call, and that is 23ms during which the process
+ * serves nothing else. The /api/auth rate limit (10/min) is keyed on the client
+ * IP, but with the default TRUSTED_PROXY_HOPS=0 that IP comes from a spoofable
+ * header (see lib/rate-limit.ts), so an attacker rotating the header gets
+ * effectively unlimited buckets — each request buying 23ms of dead process.
+ * Running async does not stop the spoofing, but it removes the amplification
+ * that made it worth doing.
+ */
+function scryptAsync(password: string, salt: string, keylen: number): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    crypto.scrypt(password, salt, keylen, (err, derivedKey) => {
+      if (err) reject(err);
+      else resolve(derivedKey);
+    });
+  });
+}
+
 /**
  * Native SCrypt verify (format: 'scrypt:salt:hash_hex')
  */
-function verifyScrypt(password: string, stored: string): boolean {
+async function verifyScrypt(password: string, stored: string): Promise<boolean> {
   if (!stored.startsWith('scrypt:')) return false;
 
   try {
     const [, salt, hashHex] = stored.split(':');
-    const key = crypto.scryptSync(password, salt, 64);
+    const key = await scryptAsync(password, salt, 64);
     const expectedKey = Buffer.from(hashHex, 'hex');
     if (key.length !== expectedKey.length) return false;
     return crypto.timingSafeEqual(key, expectedKey);
@@ -38,9 +58,9 @@ function verifyScrypt(password: string, stored: string): boolean {
 /**
  * Helper to generate an scrypt string to print in logs.
  */
-function generateScryptHash(password: string): string {
+async function generateScryptHash(password: string): Promise<string> {
   const salt = crypto.randomBytes(16).toString('hex');
-  const hash = crypto.scryptSync(password, salt, 64).toString('hex');
+  const hash = (await scryptAsync(password, salt, 64)).toString('hex');
   return `scrypt:${salt}:${hash}`;
 }
 
@@ -94,11 +114,11 @@ export function isProtected(key: string, type: 'subpage' | 'album' = 'subpage'):
  * Validate a password attempt and return a Set-Cookie header value on success.
  * Returns null if the password is wrong.
  */
-export function authenticate(
+export async function authenticate(
   key: string,
   password: string,
   type: 'subpage' | 'album' = 'subpage',
-): string | null {
+): Promise<string | null> {
   const storedPassword = findPassword(key, type);
   if (!storedPassword) return null;
 
@@ -115,7 +135,7 @@ export function authenticate(
   }
 
   if (storedPassword.startsWith('scrypt:')) {
-    isValid = verifyScrypt(password, storedPassword);
+    isValid = await verifyScrypt(password, storedPassword);
   } else {
     // Plaintext fallback (deprecated)
     // Hash both to a fixed length before constant-time comparison to prevent timing and length attacks
@@ -130,7 +150,7 @@ export function authenticate(
     isValid = crypto.timingSafeEqual(attemptHash, storedHash);
 
     if (isValid) {
-      const recommendedHash = generateScryptHash(storedPassword);
+      const recommendedHash = await generateScryptHash(storedPassword);
       console.warn(
         `\n⚠️  SECURITY WARNING: ${type === 'subpage' ? 'Subpage' : 'Album'} "${key}" is using a plaintext password in gallery.yaml.\n` +
           `   Please replace it with this native secure hash:\n\n   ${recommendedHash}\n`,
diff --git a/lib/config/index.ts b/lib/config/index.ts
index bd47dd7..0ba193e 100644
--- a/lib/config/index.ts
+++ b/lib/config/index.ts
@@ -21,6 +21,34 @@ export function invalidateConfigCache(): void {
   clearYamlCache();
 }
 
+/**
+ * getConfig(), but returns null instead of throwing on a gallery.yaml that
+ * cannot be derived.
+ *
+ * getConfig() throws for three shapes the admin page builder is able to write:
+ * a gallery with neither albums nor subpages, a subpage with no name, and a
+ * subpage with neither albums nor sections. A throw inside a *layout* is not
+ * caught by app/error.tsx — that needs a global-error boundary — so the site
+ * and /admin would go down together, locking the user out of the only tool that
+ * can undo the save. That is issue #326's failure mode reached through an
+ * invalid config rather than a missing one.
+ *
+ * Callers should treat null exactly like `needsSetup`: show the setup screen,
+ * and keep /admin reachable.
+ */
+export function getConfigOrNull(): AppConfig | null {
+  try {
+    return getConfig();
+  } catch (error) {
+    console.error(
+      '[Folio] content/gallery.yaml could not be loaded — serving the setup screen. ' +
+        'Fix the file or restore a backup from content/.backups/:',
+      error,
+    );
+    return null;
+  }
+}
+
 /** Converts raw YAML grid overrides into a typed partial GridConfig. */
 export function buildSubpageGrid(raw?: {
   columns?: number;
@@ -45,56 +73,28 @@ export function buildSubpageGrid(raw?: {
   };
 }
 
-export function getConfig(): AppConfig {
-  // No in-memory config cache: admin saves can land in a different
-  // worker/process than page rendering, so a per-worker cache goes stale
-  // until restart. Freshness comes from the mtime-checked YAML cache in
-  // loadYaml() — a statSync per file, negligible next to Immich API calls.
-  const apiUrl = env.IMMICH_API_URL;
-  const apiKey = env.IMMICH_API_KEY;
-  const authSecret = resolveAuthSecret();
-
-  const gallery = loadYaml<GalleryYaml>('gallery.yaml');
-  const settings = loadYaml<SettingsYaml>('settings.yaml') || {};
-
-  if (!gallery || !apiKey || !apiUrl) {
-    // Return dummy config if gallery.yaml is missing
-    return {
-      immich: { apiUrl: `${apiUrl}/api`, apiKey },
-      authSecret,
-      albums: [],
-      standaloneAlbums: [],
-      subpages: [],
-      siteTitle: env.SITE_TITLE || 'Immich Folio',
-      siteSubtitle: env.SITE_SUBTITLE || 'Setup Required',
-      lang: 'en',
-      seo: {
-        title: 'Setup Required',
-        description: 'Please configure Immich Folio',
-        noIndex: true,
-        noFollow: true,
-      },
-      heroImages: [],
-      exifOnHover: true,
-      grid: { columns: 3, gap: 12, aspectRatio: '1', layout: 'masonry' },
-      theme: resolveTheme('studio'),
-      footer: null,
-      legal: { enabled: false, name: '', address: '', zipCity: '', country: '' },
-      map: false,
-      transitions: false,
-      albumOverrides: {},
-      albumDescriptions: {},
-      albumPasswords: {},
-      albumHeroImages: {},
-      cacheTtl: env.CACHE_TTL * 1000,
-      rateLimitRpm: env.RATE_LIMIT_RPM,
-      trustedProxyHops: env.TRUSTED_PROXY_HOPS,
-      needsSetup: true,
-    };
-  }
-
-  const theme = resolveTheme(settings.theme);
+/** The parts of AppConfig that come from gallery.yaml. */
+export interface GalleryDerivation {
+  albums: string[];
+  standaloneAlbums: string[];
+  subpages: SubpageConfig[];
+  albumOverrides: Record<string, string>;
+  albumDescriptions: Record<string, string>;
+  albumPasswords: Record<string, string>;
+  albumHeroImages: Record<string, string>;
+}
 
+/**
+ * Derive the gallery half of AppConfig, throwing on a structure that cannot be
+ * represented: no albums and no subpages, a subpage with no name, a subpage
+ * with neither albums nor sections.
+ *
+ * Extracted from getConfig() so the admin PUT can run the *real* derivation
+ * against a proposed gallery before writing it. Re-implementing the three
+ * checks in the route would guarantee drift; write-then-verify-then-roll-back
+ * would leave a window where other requests read the broken config.
+ */
+export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
   const albumOverrides: Record<string, string> = {};
   const albumDescriptions: Record<string, string> = {};
   const albumPasswords: Record<string, string> = {};
@@ -103,7 +103,10 @@ export function getConfig(): AppConfig {
   function processAlbumEntry(
     entry:
       | string
-      | Record<string, string | { title: string; description?: string; password?: string; heroImage?: string }>,
+      | Record<
+          string,
+          string | { title: string; description?: string; password?: string; heroImage?: string }
+        >,
     context: string,
   ): string {
     if (typeof entry === 'string') {
@@ -118,7 +121,18 @@ export function getConfig(): AppConfig {
       if (value.title) albumOverrides[validatedUuid] = value.title;
       if (value.description) albumDescriptions[validatedUuid] = value.description;
       if (value.password) albumPasswords[validatedUuid] = value.password;
-      if (value.heroImage) albumHeroImages[validatedUuid] = value.heroImage;
+      // The album ID (the key) is validated above; the hero asset ID is a
+      // separate UUID and was previously stored raw. It flows to encodeAssetId
+      // via app/[...path]/page.tsx, which encrypts whatever it is handed — so a
+      // typo here produced a well-formed URL that 404s forever, with nothing in
+      // the log naming the cause. Every other ID in this file goes through
+      // validateUuid; this one was the gap.
+      if (value.heroImage) {
+        albumHeroImages[validatedUuid] = validateUuid(
+          value.heroImage,
+          `${context} heroImage for album ${validatedUuid}`,
+        );
+      }
     }
     return validatedUuid;
   }
@@ -209,11 +223,83 @@ export function getConfig(): AppConfig {
   const subpageAlbumIds = new Set(subpages.flatMap((sp) => sp.albumIds));
   const allAlbumIds = [...new Set([...standaloneAlbumIds, ...subpageAlbumIds])];
 
+  return {
+    albums: allAlbumIds,
+    standaloneAlbums: standaloneAlbumIds.filter((id) => !subpageAlbumIds.has(id)),
+    subpages,
+    albumOverrides,
+    albumDescriptions,
+    albumPasswords,
+    albumHeroImages,
+  };
+}
+
+export function getConfig(): AppConfig {
+  // No in-memory config cache: admin saves can land in a different
+  // worker/process than page rendering, so a per-worker cache goes stale
+  // until restart. Freshness comes from the mtime-checked YAML cache in
+  // loadYaml() — a statSync per file, negligible next to Immich API calls.
+  const apiUrl = env.IMMICH_API_URL;
+  const apiKey = env.IMMICH_API_KEY;
+  const authSecret = resolveAuthSecret();
+
+  const gallery = loadYaml<GalleryYaml>('gallery.yaml');
+  const settings = loadYaml<SettingsYaml>('settings.yaml') || {};
+
+  if (!gallery || !apiKey || !apiUrl) {
+    // Return dummy config if gallery.yaml is missing
+    return {
+      immich: { apiUrl: `${apiUrl}/api`, apiKey },
+      authSecret,
+      albums: [],
+      standaloneAlbums: [],
+      subpages: [],
+      siteTitle: env.SITE_TITLE || 'Immich Folio',
+      siteSubtitle: env.SITE_SUBTITLE || 'Setup Required',
+      lang: 'en',
+      seo: {
+        title: 'Setup Required',
+        description: 'Please configure Immich Folio',
+        noIndex: true,
+        noFollow: true,
+      },
+      heroImages: [],
+      exifOnHover: true,
+      grid: { columns: 3, gap: 12, aspectRatio: '1', layout: 'masonry' },
+      theme: resolveTheme('studio'),
+      footer: null,
+      legal: { enabled: false, name: '', address: '', zipCity: '', country: '' },
+      map: false,
+      transitions: false,
+      albumOverrides: {},
+      albumDescriptions: {},
+      albumPasswords: {},
+      albumHeroImages: {},
+      cacheTtl: env.CACHE_TTL * 1000,
+      immichTimeoutMs: env.IMMICH_TIMEOUT_MS,
+      rateLimitRpm: env.RATE_LIMIT_RPM,
+      trustedProxyHops: env.TRUSTED_PROXY_HOPS,
+      needsSetup: true,
+    };
+  }
+
+  const theme = resolveTheme(settings.theme);
+
+  const {
+    albums: allAlbumIds,
+    standaloneAlbums,
+    subpages,
+    albumOverrides,
+    albumDescriptions,
+    albumPasswords,
+    albumHeroImages,
+  } = deriveGallery(gallery);
+
   return {
     immich: { apiUrl: `${apiUrl}/api`, apiKey },
     authSecret,
     albums: allAlbumIds,
-    standaloneAlbums: standaloneAlbumIds.filter((id) => !subpageAlbumIds.has(id)),
+    standaloneAlbums,
     subpages,
     siteTitle: settings.title ?? env.SITE_TITLE,
     siteSubtitle: settings.subtitle ?? env.SITE_SUBTITLE,
@@ -270,6 +356,7 @@ export function getConfig(): AppConfig {
     albumPasswords,
     albumHeroImages,
     cacheTtl: env.CACHE_TTL * 1000,
+    immichTimeoutMs: env.IMMICH_TIMEOUT_MS,
     rateLimitRpm: env.RATE_LIMIT_RPM,
     trustedProxyHops: env.TRUSTED_PROXY_HOPS,
     needsSetup: false,
diff --git a/lib/config/schema.ts b/lib/config/schema.ts
index f1c2751..9f55dbb 100644
--- a/lib/config/schema.ts
+++ b/lib/config/schema.ts
@@ -99,6 +99,8 @@ export interface AppConfig {
   albumPasswords: Record<string, string>;
   albumHeroImages: Record<string, string>;
   cacheTtl: number;
+  /** Response-wait budget for Immich API calls. Does not cap image/video body transfer. */
+  immichTimeoutMs: number;
   rateLimitRpm: number;
   trustedProxyHops: number;
   needsSetup?: boolean;
diff --git a/lib/env.ts b/lib/env.ts
index c492219..86a38e6 100644
--- a/lib/env.ts
+++ b/lib/env.ts
@@ -9,6 +9,8 @@ export interface Env {
   SITE_TITLE: string;
   SITE_SUBTITLE: string;
   CACHE_TTL: number;
+  IMAGE_CACHE_VERSION: string;
+  IMMICH_TIMEOUT_MS: number;
   RATE_LIMIT_RPM: number;
   AUTH_SECRET?: string;
   TRUSTED_PROXY_HOPS: number;
@@ -35,6 +37,30 @@ function parseEnv(): Env {
   const cacheTtl =
     cacheTtlStr && !isNaN(parseInt(cacheTtlStr, 10)) ? parseInt(cacheTtlStr, 10) : 300;
 
+  // How long to wait on Immich before giving up. Without an explicit budget the
+  // only ceiling is undici's built-in default (minutes), and since every page is
+  // force-dynamic an Immich that accepts connections but never answers would
+  // hold each visitor's render open for that entire window.
+  //
+  // This bounds the wait for a *response*, not the transfer of an image or video
+  // body — those are legitimately slow and are not capped by this value.
+  const timeoutStr = process.env.IMMICH_TIMEOUT_MS;
+  const timeoutMs =
+    timeoutStr && !isNaN(parseInt(timeoutStr, 10)) ? parseInt(timeoutStr, 10) : 15000;
+
+  // Manual cache-buster for image and video URLs. Empty by default, so normal
+  // operation is untouched.
+  //
+  // Image responses are served `immutable` for a year, which means the browser
+  // does not revalidate at all — not even the ETag is consulted. That is the
+  // right default (these URLs are content-addressed by an encrypted asset ID),
+  // but it leaves no way to push a changed rendition: Immich regenerates
+  // thumbnails and previews when a job is re-run or a photo is rotated, and the
+  // asset ID — hence the token, hence the URL — stays the same. Bumping this
+  // value changes every image URL at once and is the only escape hatch short of
+  // rotating AUTH_SECRET.
+  const imageCacheVersion = (process.env.IMAGE_CACHE_VERSION || '').trim();
+
   const rateLimitStr = process.env.RATE_LIMIT_RPM;
   const rateLimit =
     rateLimitStr && !isNaN(parseInt(rateLimitStr, 10)) ? parseInt(rateLimitStr, 10) : 1500;
@@ -65,6 +91,10 @@ function parseEnv(): Env {
     SITE_TITLE: process.env.SITE_TITLE || 'Gallery',
     SITE_SUBTITLE: process.env.SITE_SUBTITLE || '',
     CACHE_TTL: Math.max(0, cacheTtl),
+    // Kept URL-safe: this value is appended to every image and video URL.
+    IMAGE_CACHE_VERSION: encodeURIComponent(imageCacheVersion),
+    // A sub-second budget would abort healthy requests; 0 must not mean "no timeout".
+    IMMICH_TIMEOUT_MS: Math.max(1000, timeoutMs),
     RATE_LIMIT_RPM: Math.max(1, rateLimit),
     AUTH_SECRET: process.env.AUTH_SECRET,
     TRUSTED_PROXY_HOPS: trustedProxyHops,
diff --git a/lib/imageSize.ts b/lib/imageSize.ts
new file mode 100644
index 0000000..6baee7c
--- /dev/null
+++ b/lib/imageSize.ts
@@ -0,0 +1,50 @@
+/**
+ * Resolves which Immich rendition the image proxy should fetch.
+ *
+ * Two query parameters can influence it:
+ *   ?size=  written by lib/urls.ts — the ceiling the server intends
+ *   ?w=     appended by lib/immichLoader.ts — the width next/image will display
+ *
+ * Lives here rather than in the route so it can be unit-tested: vitest.config.ts
+ * only collects lib/__tests__.
+ */
+
+import type { ImageSize } from './immich';
+
+export const VALID_SIZES: ImageSize[] = ['thumbnail', 'preview', 'original'];
+
+/** Smallest to largest — index order is the comparison. */
+const SIZE_ORDER: ImageSize[] = ['thumbnail', 'preview', 'original'];
+
+/** Map a requested pixel width to the best Immich size tier. */
+export function widthToSize(w: number): ImageSize {
+  if (w <= 250) return 'thumbnail';
+  if (w <= 1440) return 'preview';
+  return 'original';
+}
+
+function smaller(a: ImageSize, b: ImageSize): ImageSize {
+  return SIZE_ORDER.indexOf(a) <= SIZE_ORDER.indexOf(b) ? a : b;
+}
+
+/**
+ * When both parameters are present, take the **smaller** tier.
+ *
+ * `?size=` is a ceiling, not a demand: a width may lower the tier but must never
+ * raise it. Letting width win outright would be actively harmful — next/image
+ * emits widths up to 3840, and widthToSize(1920) is 'original', so every large
+ * display would download full-size originals instead of previews.
+ *
+ * Previously `?size=` won unconditionally, which made this function unreachable
+ * for any URL the app generates, since lib/urls.ts always writes `?size=`.
+ */
+export function resolveImageSize(sizeParam: string | null, widthParam: string | null): ImageSize {
+  const explicit =
+    sizeParam && VALID_SIZES.includes(sizeParam as ImageSize) ? (sizeParam as ImageSize) : null;
+
+  const w = widthParam ? parseInt(widthParam, 10) : NaN;
+  const fromWidth = !isNaN(w) && w > 0 ? widthToSize(w) : null;
+
+  if (explicit && fromWidth) return smaller(explicit, fromWidth);
+  return explicit ?? fromWidth ?? 'preview';
+}
diff --git a/lib/immich.ts b/lib/immich.ts
index e6051b5..2d7efc3 100644
--- a/lib/immich.ts
+++ b/lib/immich.ts
@@ -57,6 +57,53 @@ export interface ImmichExifInfo {
 
 export type ImageSize = 'thumbnail' | 'preview' | 'original';
 
+/**
+ * Thrown when Immich could not answer: transport failure, an error status, or
+ * a non-JSON body where JSON was requested.
+ *
+ * This is deliberately distinct from a `null` return, which means Immich *did*
+ * answer and said the resource does not exist. Conflating the two made every
+ * album URL render a hard 404 while Immich was down — including albums that
+ * exist — because the page calls `notFound()` on a null album. Only 404/410
+ * are treated as "gone"; everything else is an outage and must surface as one.
+ */
+/**
+ * Cache sentinel for "Immich answered, and the resource does not exist".
+ *
+ * The cache cannot tell a miss from a stored null — both read back as null — so
+ * absence is recorded as a distinct object identity instead.
+ *
+ * Only definitive 404/410 answers are stored. An outage throws
+ * `ImmichUnavailableError` and is never cached: pinning one would keep the
+ * gallery broken long after Immich recovered.
+ *
+ * Stored under the normal `cacheTtl` rather than a shorter negative TTL. A 404
+ * from Immich is as authoritative as a 200, and both invalidation paths
+ * (the Immich webhook and the admin panel's save/reload) clear it immediately —
+ * so a corrected asset ID takes effect at once rather than waiting out a TTL.
+ */
+const MISSING = Object.freeze({ __immichMissing: true });
+type Missing = typeof MISSING;
+
+/**
+ * `AbortSignal.timeout()` rejects with a `TimeoutError`; an explicit
+ * `controller.abort()` rejects with an `AbortError`. Both mean we gave up
+ * waiting, and both arrive as a plain DOMException.
+ */
+function isTimeout(error: unknown): boolean {
+  return error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError');
+}
+
+export class ImmichUnavailableError extends Error {
+  readonly status?: number;
+
+  constructor(message: string, status?: number) {
+    super(message);
+    this.name = 'ImmichUnavailableError';
+    this.status = status;
+  }
+}
+
 /** Enriched subpage with album metadata (for rendering cards). */
 export interface SubpageSummary {
   name: string;
@@ -84,8 +131,10 @@ class ImmichClient {
     if (this.config.needsSetup) return null;
 
     const url = `${this.config.immich.apiUrl}${endpoint}`;
+
+    let res: Response;
     try {
-      const res = await fetch(url, {
+      res = await fetch(url, {
         method: body === undefined ? 'GET' : 'POST',
         headers: {
           'x-api-key': this.config.immich.apiKey,
@@ -93,22 +142,55 @@ class ImmichClient {
           ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
         },
         ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        // JSON payloads are small, so one budget can cover the whole exchange.
+        // Without it the only ceiling is undici's default, measured in minutes.
+        signal: AbortSignal.timeout(this.config.immichTimeoutMs),
       });
-
-      if (!res.ok) {
-        console.error(`[Immich] ${res.status} ${res.statusText} for ${endpoint}`);
-        return null;
-      }
-
-      const contentType = res.headers.get('Content-Type') || '';
-      if (contentType.includes('application/json')) {
-        return (await res.json()) as T;
-      }
-      return null;
     } catch (error) {
       console.error(`[Immich] Failed to reach ${url}:`, error);
+      throw new ImmichUnavailableError(
+        isTimeout(error)
+          ? `Immich did not respond within ${this.config.immichTimeoutMs}ms for ${endpoint}`
+          : `Cannot reach Immich for ${endpoint}`,
+      );
+    }
+
+    if (!res.ok) {
+      console.error(`[Immich] ${res.status} ${res.statusText} for ${endpoint}`);
+      // Only "gone" means gone. A 5xx, a rate limit, or a rejected API key all
+      // mean Immich cannot serve us right now — rendering those as a missing
+      // album would tell visitors and crawlers the content no longer exists.
+      if (res.status !== 404 && res.status !== 410) {
+        throw new ImmichUnavailableError(
+          `Immich returned ${res.status} ${res.statusText} for ${endpoint}`,
+          res.status,
+        );
+      }
       return null;
     }
+
+    const contentType = res.headers.get('Content-Type') || '';
+    if (!contentType.includes('application/json')) {
+      // We always send Accept: application/json. Anything else is a gateway or
+      // proxy error page, not a valid answer about the resource.
+      throw new ImmichUnavailableError(
+        `Immich returned non-JSON (${contentType || 'no Content-Type'}) for ${endpoint}`,
+      );
+    }
+
+    try {
+      return (await res.json()) as T;
+    } catch (error) {
+      // The timeout also covers the body read, so an abort can surface here.
+      if (isTimeout(error)) {
+        console.error(`[Immich] Timed out reading ${url}`);
+        throw new ImmichUnavailableError(
+          `Immich did not respond within ${this.config.immichTimeoutMs}ms for ${endpoint}`,
+        );
+      }
+      console.error(`[Immich] Malformed JSON from ${url}:`, error);
+      throw new ImmichUnavailableError(`Immich returned malformed JSON for ${endpoint}`);
+    }
   }
 
   /**
@@ -129,6 +211,14 @@ class ImmichClient {
 
     const endpoint = `/assets/${encodeURIComponent(assetId)}/video/playback`;
     const url = `${this.config.immich.apiUrl}${endpoint}`;
+
+    // Bound the wait for response *headers* only. The `finally` clears the timer
+    // the moment they arrive, so the body may then stream for as long as it
+    // needs — a whole-request timeout would truncate playback mid-video and
+    // break seeking, since every range request would restart the clock.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.immichTimeoutMs);
+
     try {
       const headers: Record<string, string> = {
         'x-api-key': this.config.immich.apiKey,
@@ -137,13 +227,23 @@ class ImmichClient {
         headers['Range'] = rangeHeader;
       }
 
-      const res = await fetch(url, { headers });
+      const res = await fetch(url, { headers, signal: controller.signal });
 
-      if ((!res.ok && res.status !== 206) || !res.body) {
+      if (!res.ok && res.status !== 206) {
         console.error(`[Immich] Failed to stream video ${assetId}: ${res.status}`);
+        if (res.status !== 404 && res.status !== 410) {
+          throw new ImmichUnavailableError(
+            `Immich returned ${res.status} streaming video ${assetId}`,
+            res.status,
+          );
+        }
         return null;
       }
 
+      if (!res.body) {
+        throw new ImmichUnavailableError(`Immich returned an empty body for video ${assetId}`);
+      }
+
       return {
         stream: res.body,
         contentType: res.headers.get('Content-Type') || 'video/mp4',
@@ -152,8 +252,20 @@ class ImmichClient {
         status: res.status === 206 ? 206 : 200,
       };
     } catch (error) {
-      console.error(`[Immich] Video stream error for ${assetId}:`, error);
-      return null;
+      if (error instanceof ImmichUnavailableError) throw error;
+      console.error(
+        isTimeout(error)
+          ? `[Immich] Video ${assetId} did not respond within ${this.config.immichTimeoutMs}ms`
+          : `[Immich] Video stream error for ${assetId}:`,
+        error,
+      );
+      throw new ImmichUnavailableError(
+        isTimeout(error)
+          ? `Immich did not respond within ${this.config.immichTimeoutMs}ms for video ${assetId}`
+          : `Cannot reach Immich to stream video ${assetId}`,
+      );
+    } finally {
+      clearTimeout(timer);
     }
   }
 
@@ -172,26 +284,55 @@ class ImmichClient {
         : `/assets/${encodeURIComponent(assetId)}/thumbnail?size=${size}`;
 
     const url = `${this.config.immich.apiUrl}${endpoint}`;
+
+    // Headers-only timeout, same reasoning as streamVideo: an original-size
+    // photo is legitimately slow to transfer and must not be capped.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.immichTimeoutMs);
+
     try {
       const res = await fetch(url, {
         headers: {
           'x-api-key': this.config.immich.apiKey,
         },
+        signal: controller.signal,
       });
 
-      if (!res.ok || !res.body) {
+      if (!res.ok) {
         console.error(`[Immich] Failed to stream ${assetId}: ${res.status}`);
+        if (res.status !== 404 && res.status !== 410) {
+          throw new ImmichUnavailableError(
+            `Immich returned ${res.status} streaming asset ${assetId}`,
+            res.status,
+          );
+        }
         return null;
       }
 
+      if (!res.body) {
+        throw new ImmichUnavailableError(`Immich returned an empty body for asset ${assetId}`);
+      }
+
       return {
         stream: res.body,
         contentType: res.headers.get('Content-Type') || 'application/octet-stream',
         contentLength: res.headers.get('Content-Length'),
       };
     } catch (error) {
-      console.error(`[Immich] Stream error for ${assetId}:`, error);
-      return null;
+      if (error instanceof ImmichUnavailableError) throw error;
+      console.error(
+        isTimeout(error)
+          ? `[Immich] Asset ${assetId} did not respond within ${this.config.immichTimeoutMs}ms`
+          : `[Immich] Stream error for ${assetId}:`,
+        error,
+      );
+      throw new ImmichUnavailableError(
+        isTimeout(error)
+          ? `Immich did not respond within ${this.config.immichTimeoutMs}ms for asset ${assetId}`
+          : `Cannot reach Immich to stream asset ${assetId}`,
+      );
+    } finally {
+      clearTimeout(timer);
     }
   }
 
@@ -377,8 +518,8 @@ class ImmichClient {
     }
 
     const cacheKey = `album-${albumId}`;
-    const cached = cache.get<ImmichAlbum>(cacheKey);
-    if (cached) return cached;
+    const cached = cache.get<ImmichAlbum | Missing>(cacheKey);
+    if (cached) return cached === MISSING ? null : (cached as ImmichAlbum);
 
     if (this.pendingAlbumPromises.has(albumId)) {
       return this.pendingAlbumPromises.get(albumId)!;
@@ -392,7 +533,10 @@ class ImmichClient {
           this.request<ImmichAlbum>(`/albums/${encodeURIComponent(albumId)}`),
           this.fetchAlbumAssets(albumId),
         ]);
-        if (!album) return null;
+        if (!album) {
+          cache.set(cacheKey, MISSING, this.config.cacheTtl);
+          return null;
+        }
 
         // An album that Immich says has photos but returns none is almost
         // always a server older than 3.0, where metadata search behaves
@@ -464,8 +608,8 @@ class ImmichClient {
    */
   async getAssetInfo(assetId: string): Promise<ImmichAsset | null> {
     const cacheKey = `asset-${assetId}`;
-    const cached = cache.get<ImmichAsset>(cacheKey);
-    if (cached) return cached;
+    const cached = cache.get<ImmichAsset | Missing>(cacheKey);
+    if (cached) return cached === MISSING ? null : (cached as ImmichAsset);
 
     // ⚡ Bolt: Deduplicate concurrent requests for the same asset ID.
     // If a request for this asset is already in flight (e.g. from Promise.all in a grid),
@@ -477,7 +621,13 @@ class ImmichClient {
     const promise = (async () => {
       try {
         const asset = await this.request<ImmichAsset>(`/assets/${encodeURIComponent(assetId)}`);
-        if (!asset) return null;
+        if (!asset) {
+          // The homepage looks up every gallery.yaml hero ID on each render
+          // (app/page.tsx), and those pages are force-dynamic — so a hero photo
+          // deleted from Immich otherwise costs an upstream 404 every time.
+          cache.set(cacheKey, MISSING, this.config.cacheTtl);
+          return null;
+        }
 
         cache.set(cacheKey, asset, this.config.cacheTtl);
         return asset;
@@ -514,8 +664,14 @@ class ImmichClient {
    * Check if the Immich server is reachable.
    */
   async ping(): Promise<boolean> {
-    const res = await this.request<{ res: string }>('/server/ping');
-    return !!res;
+    try {
+      const res = await this.request<{ res: string }>('/server/ping');
+      return !!res;
+    } catch {
+      // "Is Immich reachable?" — unreachable is the answer, not an exception.
+      // Both callers (/api/health, /api/admin/status) render this as a status.
+      return false;
+    }
   }
 }
 
diff --git a/lib/rate-limit.ts b/lib/rate-limit.ts
index 7560548..8b35985 100644
--- a/lib/rate-limit.ts
+++ b/lib/rate-limit.ts
@@ -15,6 +15,39 @@ import { getConfig } from './config';
 /** Bucket key used when the client cannot be identified with any confidence. */
 const UNIDENTIFIED = 'unknown';
 
+let warnedUnidentified = false;
+
+/**
+ * Falling back to the shared bucket is the *correct* behaviour — the
+ * alternative is trusting a spoofable header — but it is silent, and silence is
+ * the problem. Every unidentified request shares one bucket per endpoint, and
+ * this is an image proxy: a single 50-photo grid issues ~50 `/api/image`
+ * requests, so the default 1500 rpm is collectively spent by roughly 30 page
+ * loads a minute. Visitors then see 429s with nothing in the log pointing at
+ * the proxy configuration that caused it.
+ *
+ * Warn once per process: enough to diagnose, not enough to flood the log.
+ */
+function unidentified(hops: number, detail: string): string {
+  if (!warnedUnidentified) {
+    warnedUnidentified = true;
+    console.warn(
+      `\n⚠️  Rate limiting cannot identify clients: ${detail}\n` +
+        `   TRUSTED_PROXY_HOPS is ${hops}, so the client IP is read ${hops} entr${hops === 1 ? 'y' : 'ies'} from the\n` +
+        `   right of X-Forwarded-For. Unidentified requests all share ONE bucket per\n` +
+        `   endpoint, which an image proxy exhausts quickly — expect 429s for everyone.\n` +
+        `   Set TRUSTED_PROXY_HOPS to the number of proxies actually in front of the app\n` +
+        `   (nginx/Traefik/Caddy = 1; add 1 for each additional layer, e.g. Cloudflare = 2).\n`,
+    );
+  }
+  return UNIDENTIFIED;
+}
+
+/** Test seam: the warning is once-per-process, which tests need to re-arm. */
+export function __resetProxyWarningForTests(): void {
+  warnedUnidentified = false;
+}
+
 /**
  * Resolve the client IP to use as a rate-limit bucket key.
  *
@@ -52,13 +85,26 @@ export function getClientIp(request: NextRequest): string {
         .filter(Boolean);
       // Chain shorter than the configured hop count means the request did not
       // traverse the full proxy chain — do not fall back to a spoofable entry.
-      return chain[chain.length - hops] ?? UNIDENTIFIED;
+      const ip = chain[chain.length - hops];
+      if (ip) return ip;
+
+      return unidentified(
+        hops,
+        `X-Forwarded-For carries ${chain.length} entr${chain.length === 1 ? 'y' : 'ies'}, ` +
+          `fewer than the ${hops} configured hop${hops === 1 ? '' : 's'}`,
+      );
     }
     // nginx's `proxy_set_header X-Real-IP $remote_addr` overwrites rather than
     // appends, so it is trustworthy — but only for a single hop, since an outer
     // proxy would leave an inner proxy's value in place.
     if (xRealIp && hops === 1) return xRealIp;
-    return UNIDENTIFIED;
+
+    return unidentified(
+      hops,
+      xRealIp
+        ? 'no X-Forwarded-For header, and X-Real-IP is only trustworthy at a single hop'
+        : 'neither X-Forwarded-For nor X-Real-IP was present',
+    );
   }
 
   // No proxy declared: headers are best-effort only. This still separates
@@ -67,6 +113,18 @@ export function getClientIp(request: NextRequest): string {
   return xRealIp ?? xForwardedFor?.split(',')[0].trim() ?? UNIDENTIFIED;
 }
 
+/**
+ * Seconds a client should wait before retrying, for the `Retry-After` header.
+ *
+ * Floored at 1. The obvious `Math.ceil((resetAt - Date.now()) / 1000)` yields 0
+ * — or a negative number — when the window is on the point of expiring, and
+ * `Retry-After: 0` tells the client to retry immediately, which is the opposite
+ * of what a 429 is for. A negative value is not valid HTTP at all.
+ */
+export function retryAfterSeconds(resetAt: number): number {
+  return Math.max(1, Math.ceil((resetAt - Date.now()) / 1000));
+}
+
 interface RateLimitEntry {
   count: number;
   expiresAt: number;
diff --git a/lib/urls.ts b/lib/urls.ts
index fa28602..3301564 100644
--- a/lib/urls.ts
+++ b/lib/urls.ts
@@ -4,9 +4,23 @@
  */
 
 import { encodeAssetId } from './tokens';
+import { env } from './env';
 import { thumbHashToBlurDataUrl, thumbHashToDominantHex } from './thumbhash';
 import type { ImmichAsset } from './immich';
 
+/**
+ * Optional cache-buster, appended to every image and video URL.
+ *
+ * These responses are served `immutable` for a year, so the browser never
+ * revalidates and the ETag is never consulted — the URL is the only thing that
+ * can invalidate a browser cache. Setting IMAGE_CACHE_VERSION changes all of
+ * them at once, which is what you want after Immich regenerates thumbnails or a
+ * photo is rotated: the asset ID does not change, so nothing else would.
+ *
+ * Empty by default — the returned URLs are then byte-identical to before.
+ */
+const cacheBuster = env.IMAGE_CACHE_VERSION ? `&v=${env.IMAGE_CACHE_VERSION}` : '';
+
 /**
  * Generate a public image proxy URL for an asset.
  */
@@ -14,7 +28,7 @@ export function imageUrl(
   assetId: string,
   size: 'thumbnail' | 'preview' | 'original' = 'preview',
 ): string {
-  return `/api/image/${encodeAssetId(assetId)}?size=${size}`;
+  return `/api/image/${encodeAssetId(assetId)}?size=${size}${cacheBuster}`;
 }
 
 /**
@@ -28,7 +42,9 @@ export function exifUrl(assetId: string): string {
  * Generate a public video proxy URL for an asset.
  */
 export function videoUrl(assetId: string): string {
-  return `/api/video/${encodeAssetId(assetId)}`;
+  // No `size` here, so the buster is the only query parameter.
+  const v = cacheBuster ? `?${cacheBuster.slice(1)}` : '';
+  return `/api/video/${encodeAssetId(assetId)}${v}`;
 }
 
 /**
diff --git a/next.config.ts b/next.config.ts
index 008bd93..43cdbfe 100644
--- a/next.config.ts
+++ b/next.config.ts
@@ -2,10 +2,10 @@ import type { NextConfig } from 'next';
 
 /**
  * Static security headers, applied to every response including /api and static
- * assets, which middleware does not cover.
+ * assets, which the proxy does not cover.
  *
  * The Content-Security-Policy is deliberately NOT set here: it needs a
- * per-request nonce and is owned exclusively by middleware.ts. Keeping the two
+ * per-request nonce and is owned exclusively by proxy.ts. Keeping the two
  * layers disjoint avoids emitting the same header twice with conflicting
  * values, which browsers may resolve by ignoring the header altogether.
  */
diff --git a/middleware.ts b/proxy.ts
similarity index 98%
rename from middleware.ts
rename to proxy.ts
index 2b21b4b..8550e5f 100644
--- a/middleware.ts
+++ b/proxy.ts
@@ -1,7 +1,7 @@
 import { NextResponse } from 'next/server';
 import type { NextRequest } from 'next/server';
 
-export function middleware(request: NextRequest) {
+export function proxy(request: NextRequest) {
   const nonce = Buffer.from(crypto.randomUUID()).toString('base64');
 
   // Define CSP directives