diff --git a/.env.local.example b/.env.local.example
index d2cc2ea..6178a1d 100644
--- a/.env.local.example
+++ b/.env.local.example
@@ -19,6 +19,12 @@ SITE_SUBTITLE=A visual journal
 # Cache TTL in seconds (integer >= 0, default: 300 = 5 minutes)
 CACHE_TTL=300
 
+# How long (in seconds) an expired cache entry may still be served while the
+# Immich server is unreachable. Keeps the public gallery online across an
+# Immich restart instead of showing an error page. Set to 0 to disable.
+# Default: 86400 (24 hours)
+STALE_MAX_AGE=86400
+
 # 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
diff --git a/CLAUDE.md b/CLAUDE.md
index 59be0de..2cc3453 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -52,7 +52,7 @@ Singleton `ImmichClient` class exported as `immich`. All Immich API calls are se
 
 - **Album allowlist** — `getAlbums()` fetches `?shared=true` albums but only returns IDs listed in `config.albums`. Requests for unlisted albums are silently rejected.
 - **Request coalescing** — pending promises are stored in `Map<id, Promise>` fields to deduplicate concurrent requests for the same album/asset (important for `Promise.all` calls in grids).
-- **In-memory LRU cache** (`lib/cache.ts`) — 200-entry LRU, configurable TTL via `CACHE_TTL`. Cache keys: `albums-list`, `album-<id>`, `asset-<id>`.
+- **In-memory LRU cache** (`lib/cache.ts`) — 200-entry LRU. Entries carry two deadlines: `staleAt` (the `CACHE_TTL` window, after which `get()` reports a miss) and `hardExpiresAt` (`STALE_MAX_AGE`, after which the entry is dropped). Between the two, `getStale()` still returns the data — `lib/immich.ts` falls back to it when a request fails with `ImmichUnavailableError`, so the gallery keeps serving the last known albums during an Immich outage instead of erroring. Definitive 404s are cached as a `MISSING` sentinel under the normal TTL and are deliberately excluded from the stale window. Cache keys: `albums-list`, `album-<id>`, `asset-<id>`.
 - **Image streaming** — `streamAsset()` proxies binary responses; never loads the full image into memory.
 
 ### Asset token security (`lib/tokens.ts`)
@@ -61,19 +61,19 @@ Singleton `ImmichClient` class exported as `immich`. All Immich API calls are se
 
 ### API routes (`app/api/`)
 
-| Route | Purpose |
-|---|---|
-| `GET /api/image/[id]` | Image proxy — decodes token, rate-limits, streams from Immich |
-| `GET /api/exif/[id]` | EXIF data for lightbox panel |
-| `POST /api/auth` | Password submission → sets `HttpOnly` cookie |
-| `GET /api/og` | Dynamic OG image generation (rate-limited) |
-| `GET /api/map` | Aggregated GPS coordinates for map view |
-| `GET /api/health` | Health check |
-| `GET/POST/DELETE /api/admin/auth` | Admin login, session check, logout |
-| `GET/PUT /api/admin/gallery` | Read/write `gallery.yaml` |
-| `GET/PUT /api/admin/settings` | Read/write `settings.yaml` |
-| `GET /api/admin/albums` | Browse all shared Immich albums (admin-only) |
-| `POST /api/admin/reload` | Invalidate config + Immich cache |
+| Route                             | Purpose                                                       |
+| --------------------------------- | ------------------------------------------------------------- |
+| `GET /api/image/[id]`             | Image proxy — decodes token, rate-limits, streams from Immich |
+| `GET /api/exif/[id]`              | EXIF data for lightbox panel                                  |
+| `POST /api/auth`                  | Password submission → sets `HttpOnly` cookie                  |
+| `GET /api/og`                     | Dynamic OG image generation (rate-limited)                    |
+| `GET /api/map`                    | Aggregated GPS coordinates for map view                       |
+| `GET /api/health`                 | Health check                                                  |
+| `GET/POST/DELETE /api/admin/auth` | Admin login, session check, logout                            |
+| `GET/PUT /api/admin/gallery`      | Read/write `gallery.yaml`                                     |
+| `GET/PUT /api/admin/settings`     | Read/write `settings.yaml`                                    |
+| `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` (`lib/imageSize.ts`).
 
@@ -82,6 +82,7 @@ The image proxy maps requested pixel widths (`?w=`) to Immich size tiers: `≤25
 ### Routing (`app/[...path]/page.tsx`)
 
 Single catch-all route handles three cases:
+
 1. `/[subpage-slug]/[album-slug]` — renders album detail with back-link to subpage
 2. `/[subpage-slug]` — if subpage has >1 album, renders `SubpageGridView`; if exactly 1 album, renders `AlbumDetailView` directly
 3. `/[album-slug]` — standalone album detail
@@ -134,3 +135,4 @@ Next.js 16 renamed the `middleware` file convention to `proxy`: the file is `pro
 - **All Immich data flows server-side** — raw asset UUIDs must never appear in client-rendered HTML or JS. Always use `encodeAssetId()` / `imageUrl()` / `exifUrl()` from `lib/urls.ts` before passing IDs to components.
 - **Rate-limit all expensive endpoints** — apply `checkRateLimit` from `lib/rate-limit.ts` to any route doing heavy computation or upstream API calls.
 - **Commit style** — Conventional Commits: `feat:`, `fix:`, `security:`, `docs:`, `chore:`.
+- **Route handlers are testable** — `vitest.config.ts` includes `app/**/__tests__/**/*.test.ts`. Logic that lives in a route (auth guards, header sanitisation) belongs in a route-level test; do not extract it into `lib/` purely to make it reachable by the test runner.
diff --git a/README.md b/README.md
index 61b301e..2a93690 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,7 @@ 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
+STALE_MAX_AGE=86400                    # seconds an expired cache entry survives during an outage, default: 86400 (24h), 0 disables
 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
@@ -191,6 +192,16 @@ The container includes a built-in health check at `/api/health`:
 curl http://localhost:7211/api/health
 ```
 
+### Behaviour when Immich is unreachable
+
+Immich Folio buffers your gallery rather than merely proxying it:
+
+- Album and asset pages keep serving the last known good data for up to `STALE_MAX_AGE`, so a restarting or briefly unreachable Immich does not take the public site down with it.
+- Once nothing cached is left, they return `503`, never `404` — a `404` would tell search engines to drop a URL for content that still exists.
+- Outages are never cached, so the gallery recovers as soon as Immich does.
+
+The cache lives in the process, so it is empty right after a container restart.
+
 ### Reverse Proxy
 
 Put Immich Folio behind nginx / Caddy / Traefik with TLS. Example Caddy config:
diff --git a/app/[...path]/loading.tsx b/app/[...path]/loading.tsx
new file mode 100644
index 0000000..f604de3
--- /dev/null
+++ b/app/[...path]/loading.tsx
@@ -0,0 +1,20 @@
+/**
+ * Instant shell for album and subpage routes. These are force-dynamic and wait
+ * on a live Immich round-trip — up to IMMICH_TIMEOUT_MS when the server is
+ * struggling — so without this the viewer stares at a blank page.
+ */
+
+import styles from '../loading.module.css';
+
+export default function Loading() {
+  return (
+    <>
+      <div className={styles.heading} aria-hidden="true" />
+      <div className={styles.grid} role="status" aria-label="Loading photos">
+        {Array.from({ length: 9 }).map((_, i) => (
+          <div key={i} className={styles.tile} />
+        ))}
+      </div>
+    </>
+  );
+}
diff --git a/app/api/admin/__tests__/admin-guards.test.ts b/app/api/admin/__tests__/admin-guards.test.ts
new file mode 100644
index 0000000..e86e75d
--- /dev/null
+++ b/app/api/admin/__tests__/admin-guards.test.ts
@@ -0,0 +1,158 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('@/lib/admin/auth', () => ({
+  isAdminEnabled: vi.fn(),
+  isAdminAuthenticated: vi.fn(),
+  COOKIE_NAME: 'folio_admin_session',
+}));
+
+import { isAdminEnabled, isAdminAuthenticated } from '@/lib/admin/auth';
+
+const mockEnabled = isAdminEnabled as unknown as ReturnType<typeof vi.fn>;
+const mockAuthed = isAdminAuthenticated as unknown as ReturnType<typeof vi.fn>;
+
+/**
+ * Every guarded admin route handler. Adding a new /api/admin route means
+ * adding a row here — a route that forgets its guard then fails this suite
+ * instead of shipping. /api/admin/auth is deliberately absent: it is the login
+ * endpoint and must stay reachable without a session.
+ */
+const ROUTES: {
+  name: string;
+  path: string;
+  load: () => Promise<Record<string, unknown>>;
+  method: 'GET' | 'PUT' | 'POST' | 'DELETE';
+  args: () => unknown[];
+}[] = [
+  {
+    name: 'GET /api/admin/gallery',
+    path: 'gallery',
+    load: () => import('../gallery/route'),
+    method: 'GET',
+    args: () => [],
+  },
+  {
+    name: 'PUT /api/admin/gallery',
+    path: 'gallery',
+    load: () => import('../gallery/route'),
+    method: 'PUT',
+    args: () => [new Request('http://localhost/api/admin/gallery', { method: 'PUT', body: '{}' })],
+  },
+  {
+    name: 'GET /api/admin/settings',
+    path: 'settings',
+    load: () => import('../settings/route'),
+    method: 'GET',
+    args: () => [],
+  },
+  {
+    name: 'PUT /api/admin/settings',
+    path: 'settings',
+    load: () => import('../settings/route'),
+    method: 'PUT',
+    args: () => [new Request('http://localhost/api/admin/settings', { method: 'PUT', body: '{}' })],
+  },
+  {
+    name: 'GET /api/admin/albums',
+    path: 'albums',
+    load: () => import('../albums/route'),
+    method: 'GET',
+    args: () => [],
+  },
+  {
+    name: 'POST /api/admin/reload',
+    path: 'reload',
+    load: () => import('../reload/route'),
+    method: 'POST',
+    args: () => [],
+  },
+  {
+    name: 'GET /api/admin/status',
+    path: 'status',
+    load: () => import('../status/route'),
+    method: 'GET',
+    args: () => [],
+  },
+  {
+    name: 'GET /api/admin/assets',
+    path: 'assets',
+    load: () => import('../assets/route'),
+    method: 'GET',
+    args: () => [new Request('http://localhost/api/admin/assets')],
+  },
+  {
+    name: 'GET /api/admin/thumbnail/[id]',
+    path: 'thumbnail/[id]',
+    load: () => import('../thumbnail/[id]/route'),
+    method: 'GET',
+    args: () => [
+      new Request('http://localhost/api/admin/thumbnail/abc'),
+      { params: Promise.resolve({ id: 'abc' }) },
+    ],
+  },
+  {
+    name: 'GET /api/admin/albums/[albumId]/assets',
+    path: 'albums/[albumId]/assets',
+    load: () => import('../albums/[albumId]/assets/route'),
+    method: 'GET',
+    args: () => [
+      new Request('http://localhost/api/admin/albums/a1/assets'),
+      { params: Promise.resolve({ albumId: 'a1' }) },
+    ],
+  },
+];
+
+describe('admin route guards', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  for (const route of ROUTES) {
+    it(`${route.name} returns 403 when the admin panel is disabled`, async () => {
+      mockEnabled.mockReturnValue(false);
+      mockAuthed.mockResolvedValue(false);
+
+      const mod = await route.load();
+      const handler = mod[route.method] as (...a: unknown[]) => Promise<Response>;
+      const res = await handler(...route.args());
+
+      expect(res.status).toBe(403);
+    });
+
+    it(`${route.name} returns 401 without a valid session`, async () => {
+      mockEnabled.mockReturnValue(true);
+      mockAuthed.mockResolvedValue(false);
+
+      const mod = await route.load();
+      const handler = mod[route.method] as (...a: unknown[]) => Promise<Response>;
+      const res = await handler(...route.args());
+
+      expect(res.status).toBe(401);
+    });
+  }
+
+  it('has a row for every route module under app/api/admin', async () => {
+    const fs = await import('fs');
+    const path = await import('path');
+    const adminDir = path.join(process.cwd(), 'app/api/admin');
+
+    const found: string[] = [];
+    const walk = (dir: string) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (entry.name === '__tests__') continue;
+          walk(full);
+        } else if (entry.name === 'route.ts') {
+          found.push(path.relative(adminDir, path.dirname(full)));
+        }
+      }
+    };
+    walk(adminDir);
+
+    const covered = new Set(ROUTES.map((r) => r.path));
+    const uncovered = found.filter((p) => p !== 'auth' && !covered.has(p));
+
+    expect(uncovered, `Admin routes with no guard test: ${uncovered.join(', ')}`).toEqual([]);
+  });
+});
diff --git a/app/api/image/__tests__/image-route.test.ts b/app/api/image/__tests__/image-route.test.ts
new file mode 100644
index 0000000..3d0c681
--- /dev/null
+++ b/app/api/image/__tests__/image-route.test.ts
@@ -0,0 +1,114 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { NextRequest } from 'next/server';
+import { GET } from '../[id]/route';
+import { encodeAssetId } from '@/lib/tokens';
+import { immich, ImmichUnavailableError } from '@/lib/immich';
+
+vi.mock('@/lib/immich', async () => {
+  const actual = await vi.importActual<typeof import('@/lib/immich')>('@/lib/immich');
+  return {
+    // Keep the real error class — the route branches on `instanceof`.
+    ImmichUnavailableError: actual.ImmichUnavailableError,
+    immich: { streamAsset: vi.fn() },
+  };
+});
+
+const mockStream = immich.streamAsset as unknown as ReturnType<typeof vi.fn>;
+
+const ASSET_ID = '11111111-2222-3333-4444-555555555555';
+
+/** Stream stub — the route only forwards the body, it never reads it. */
+function fakeBody(contentType: string) {
+  return {
+    stream: new ReadableStream({
+      start(controller) {
+        controller.enqueue(new Uint8Array([1, 2, 3]));
+        controller.close();
+      },
+    }),
+    contentType,
+    contentLength: '3',
+  };
+}
+
+function call(token: string, query = '', headers?: Record<string, string>) {
+  const req = new NextRequest(`http://localhost/api/image/${token}${query}`, { headers });
+  return GET(req, { params: Promise.resolve({ id: token }) });
+}
+
+describe('GET /api/image/[id]', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('rejects a raw Immich UUID instead of an encoded token', async () => {
+    const res = await call(ASSET_ID);
+    expect(res.status).toBe(400);
+    expect(mockStream).not.toHaveBeenCalled();
+  });
+
+  it('rejects a syntactically broken token', async () => {
+    const res = await call('v2:not-valid-base64url!!');
+    expect(res.status).toBe(400);
+    expect(mockStream).not.toHaveBeenCalled();
+  });
+
+  it('serves a valid token', async () => {
+    mockStream.mockResolvedValue(fakeBody('image/jpeg'));
+    const res = await call(encodeAssetId(ASSET_ID));
+    expect(res.status).toBe(200);
+    expect(mockStream).toHaveBeenCalledWith(ASSET_ID, 'preview');
+  });
+
+  // Regression guard for the stored-XSS fix in c2fa8e7. An SVG served as
+  // image/svg+xml executes script in the browser under our own origin.
+  // This logic lives in the route and cannot be extracted the way
+  // lib/imageSize.ts was, so a route-level test is the only way to pin it.
+  it.each([
+    ['image/svg+xml', 'application/octet-stream'],
+    ['text/xml', 'application/octet-stream'],
+    ['text/html', 'application/octet-stream'],
+    ['application/octet-stream', 'image/jpeg'],
+    ['image/jpeg', 'image/jpeg'],
+    ['image/webp', 'image/webp'],
+  ])('rewrites upstream Content-Type %s to %s', async (upstream, expected) => {
+    mockStream.mockResolvedValue(fakeBody(upstream));
+    const res = await call(encodeAssetId(ASSET_ID));
+    expect(res.headers.get('Content-Type')).toBe(expected);
+  });
+
+  it('returns 304 with no body when the ETag matches', async () => {
+    mockStream.mockResolvedValue(fakeBody('image/jpeg'));
+    const token = encodeAssetId(ASSET_ID);
+
+    const first = await call(token);
+    const etag = first.headers.get('ETag');
+    expect(etag).toBeTruthy();
+
+    const res = await call(token, '', { 'if-none-match': etag as string });
+    expect(res.status).toBe(304);
+    expect(await res.text()).toBe('');
+  });
+
+  it('never leaks the raw asset UUID in response headers', async () => {
+    mockStream.mockResolvedValue(fakeBody('image/jpeg'));
+    const res = await call(encodeAssetId(ASSET_ID));
+    const headerDump = JSON.stringify([...res.headers.entries()]);
+    expect(headerDump).not.toContain(ASSET_ID);
+  });
+
+  it('404s when the asset is genuinely gone', async () => {
+    mockStream.mockResolvedValue(null);
+    const res = await call(encodeAssetId(ASSET_ID));
+    expect(res.status).toBe(404);
+    expect(res.headers.get('Cache-Control')).toBe('no-store');
+  });
+
+  it('503s when Immich is unavailable, and does not let it be cached', async () => {
+    mockStream.mockRejectedValue(new ImmichUnavailableError('upstream down'));
+    const res = await call(encodeAssetId(ASSET_ID));
+    expect(res.status).toBe(503);
+    expect(res.headers.get('Cache-Control')).toBe('no-store');
+    expect(res.headers.get('Retry-After')).toBeTruthy();
+  });
+});
diff --git a/app/loading.module.css b/app/loading.module.css
new file mode 100644
index 0000000..009db21
--- /dev/null
+++ b/app/loading.module.css
@@ -0,0 +1,47 @@
+/* Skeleton placeholders shown while a dynamic page waits on Immich. */
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(var(--grid-columns, 3), 1fr);
+  gap: var(--grid-gap, 12px);
+}
+
+.tile {
+  aspect-ratio: var(--grid-aspect-ratio, 1);
+  border-radius: var(--radius-sm);
+  background: var(--bg-secondary);
+  animation: skeleton-pulse 1.6s ease-in-out infinite;
+}
+
+.heading {
+  height: 2.5rem;
+  width: min(320px, 60%);
+  border-radius: var(--radius-sm);
+  background: var(--bg-secondary);
+  margin-bottom: 24px;
+  animation: skeleton-pulse 1.6s ease-in-out infinite;
+}
+
+@keyframes skeleton-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+
+  50% {
+    opacity: 0.45;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .tile,
+  .heading {
+    animation: none;
+  }
+}
+
+@media (max-width: 640px) {
+  .grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
diff --git a/app/loading.tsx b/app/loading.tsx
new file mode 100644
index 0000000..ddc675f
--- /dev/null
+++ b/app/loading.tsx
@@ -0,0 +1,15 @@
+/**
+ * Instant shell for the homepage.
+ */
+
+import styles from './loading.module.css';
+
+export default function Loading() {
+  return (
+    <div className={styles.grid} role="status" aria-label="Loading gallery">
+      {Array.from({ length: 6 }).map((_, i) => (
+        <div key={i} className={styles.tile} />
+      ))}
+    </div>
+  );
+}
diff --git a/docs/brainstorm-2026-08-05.md b/docs/brainstorm-2026-08-05.md
new file mode 100644
index 0000000..1c3ad30
--- /dev/null
+++ b/docs/brainstorm-2026-08-05.md
@@ -0,0 +1,336 @@
+# Feature-Brainstorm: Verbreitung & Robustheit
+
+_Stand: 2026-08-05 · Basis: v0.9.1 · Fokus: Open-Source-Verbreitung + Betrieb & Robustheit_
+
+Dieses Dokument ergänzt [`ideas.md`](ideas.md) (Präsentations-Features) und
+[`brainstorm.md`](brainstorm.md) (Stand Mai 2026). Es wiederholt deren Ideen nicht,
+sondern nimmt eine andere Perspektive ein: **Was hindert andere Fotografen daran,
+Folio einzusetzen — und was geht im Betrieb kaputt?**
+
+Alle Ideen sind gegen den tatsächlichen Code-Stand geprüft. Aufwand: XS (Stunden),
+S (1 Tag), M (2–5 Tage), L (Wochen).
+
+---
+
+## Kontext: Was seit Mai dazugekommen ist
+
+Aus `brainstorm.md` bereits erledigt: **Map-View** (`app/map/page.tsx`,
+`components/MapView.tsx`), Video-Support, Webhook-Invalidierung, Album-Beschreibungen.
+
+Weiterhin offen aus den alten Listen (hier bewusst _nicht_ nochmal ausgeführt):
+RSS-Feed, Slideshow, Download-Button, Share-Link, Fullscreen, Timeline-View,
+Immich Smart Search, Photo Stories, PWA, Watermarking, Client-Proofing, EXIF-Analytics.
+
+---
+
+## A. Betrieb & Robustheit
+
+### A1. Fehler-, Lade- und 404-Boundaries — **XS, hoher Impact**
+
+**Befund:** Im gesamten `app/`-Verzeichnis existiert keine einzige `error.tsx`,
+`global-error.tsx`, `loading.tsx` oder `not-found.tsx`.
+
+Weil alle Seiten `dynamic = 'force-dynamic'` sind und live gegen Immich laufen,
+heißt das: Immich neu gestartet, API-Key rotiert, Netzwerk kurz weg → der Besucher
+bekommt die generische Next.js-Fehlerseite. Ein Tippfehler in der URL → ebenfalls
+ungestylt. Für ein Produkt, dessen Verkaufsargument „schön" ist, ist das der
+peinlichste mögliche Zustand.
+
+**Umsetzung:** `app/error.tsx` und `app/global-error.tsx` im Theme-Look mit
+Retry-Button; `app/not-found.tsx`; `loading.tsx` pro Route-Segment mit
+ThumbHash-Skeletons (`lib/thumbhash.ts` liefert die Bausteine schon).
+
+**Warum zuerst:** Billigste Maßnahme mit der größten Wirkung auf den
+wahrgenommenen Reifegrad.
+
+---
+
+### A2. Stale-while-error — Galerie bleibt online, wenn Immich weg ist — **M, hoher Impact**
+
+**Befund:** `lib/cache.ts` ist ein 200-Einträge-LRU mit harter TTL (`CACHE_TTL`,
+Default 300s). Läuft ein Eintrag ab und Immich antwortet nicht, gibt es keinen
+Fallback — die Seite ist tot.
+
+**Idee:** Abgelaufene Einträge nicht wegwerfen, sondern als *stale* markieren.
+Bei Upstream-Fehler den veralteten Eintrag trotzdem ausliefern, im Hintergrund
+erneut versuchen, und (optional konfigurierbar) einen dezenten Hinweis
+einblenden. Das öffentliche Portfolio überlebt damit ein Immich-Update,
+ein Backup-Fenster oder einen NAS-Reboot.
+
+**Warum das zieht:** Genau das ist die Angst des Self-Hosters — „meine
+öffentliche Seite geht offline, weil mein privater Server hustet". Folio als
+_Puffer_ vor Immich zu positionieren statt als bloßen Proxy ist ein echtes
+Argument.
+
+**Anker:** `lib/cache.ts`, `lib/immich.ts` (Request-Coalescing ist schon da und
+passt gut dazu).
+
+---
+
+### A3. Persistenter Bild-Cache auf Platte — **M, hoher Impact auf schwacher Hardware**
+
+**Befund:** `streamAsset()` proxied jedes Bild bei jedem Kaltstart erneut von
+Immich. Der LRU-Cache hält nur Metadaten, keine Bytes.
+
+**Idee:** Optionales Cache-Volume (`CACHE_DIR`), in dem proxied Thumbnails und
+Previews pro Größen-Tier landen. Die Asset-Tokens sind bereits deterministisch
+(`lib/tokens.ts`: gleiche UUID → gleicher Token), also ist der Cache-Key
+geschenkt. Mit LRU-Eviction und konfigurierbarem Größenlimit.
+
+**Warum:** Die typische Zielgruppe hostet auf Synology, RasPi oder einem alten
+NUC. Dort ist wiederholtes Proxying der Flaschenhals — und es hält gleichzeitig
+den Immich-Server unter Last.
+
+---
+
+### A4. ISR statt `force-dynamic`, getrieben vom vorhandenen Webhook — **M**
+
+**Befund:** Alle Seiten sind `force-dynamic`. Gleichzeitig existiert bereits
+`POST /api/webhook` mit HMAC-Signatur und gezielter Cache-Invalidierung.
+
+**Idee:** Seiten auf Next.js-Cache-Tags umstellen (`albums`, `album-<id>`) und
+den Webhook `revalidateTag()` aufrufen lassen statt nur den internen LRU zu
+leeren. Ergebnis: statisch schnelle Auslieferung, trotzdem sofort aktuell,
+sobald sich in Immich etwas ändert.
+
+**Achtung:** Passwortgeschützte Subpages/Alben müssen dynamisch bleiben —
+die Cookie-Prüfung in `lib/auth.ts` darf nicht wegcachen. Das ist die eigentliche
+Arbeit an dieser Idee, nicht das Umstellen selbst.
+
+_Stand in `ideas.md` schon als Einzeiler; hier mit dem Webhook als Auslöser
+konkretisiert._
+
+---
+
+### A5. Config-Doctor — **S, hoher Impact auf Support-Aufwand**
+
+**Befund:** `GET /api/admin/status` existiert bereits als Ansatzpunkt. Es gibt
+aber keine Stelle, die typische Fehlkonfigurationen aktiv meldet.
+
+**Idee:** Ein Diagnose-Panel im Admin (plus `npm run doctor` fürs Terminal), das
+prüft:
+
+- `AUTH_SECRET` gesetzt und ausreichend lang?
+- `TRUSTED_PROXY_HOPS` plausibel? — tatsächlich eingehende `X-Forwarded-For`-Kette
+  messen und mit dem konfigurierten Wert vergleichen. Ein falscher Wert legt das
+  Rate-Limiting still oder macht es spoofbar; heute merkt das niemand.
+- Existieren alle Album-IDs aus `gallery.yaml` noch in Immich?
+- Reichen die Permissions des API-Keys?
+- Liegen Passwörter im Klartext statt als `scrypt:`-Hash? (`lib/auth.ts` warnt
+  bislang nur in die Logs, wo es keiner liest.)
+- Ist `content/` beschreibbar? (war real ein Bug — siehe Commit-History)
+
+**Warum:** Fast jedes „geht bei mir nicht"-Issue eines Self-Hosting-Projekts ist
+eine dieser Zeilen. Der Doctor beantwortet sie, bevor das Issue aufgemacht wird.
+
+---
+
+### A6. `AUTH_SECRET` automatisch bereitstellen — **XS**
+
+**Befund:** `lib/secret.ts` wirft in Production hart, wenn `AUTH_SECRET` fehlt.
+Korrekt gedacht (nicht auf eine ratbare Konstante zurückfallen), aber es
+bedeutet: `docker run` ohne gesetztes Secret → App startet nicht, mit einem
+Fehler, den Einsteiger nicht sofort einordnen.
+
+**Idee:** Fehlt die Env-Variable, beim ersten Start ein Zufalls-Secret erzeugen
+und nach `content/.secret` (Mode 0600) persistieren. Weiterhin warnen, aber
+nicht blockieren. Env-Variable behält Vorrang.
+
+**Trade-off, der dokumentiert gehört:** Das Secret liegt dann im Content-Volume
+statt in der Umgebung. Für ein Self-Hosted-Portfolio ist das der richtige
+Kompromiss — das Volume enthält ohnehin die Galerie-Passwörter.
+
+---
+
+### A7. Strukturierte Logs + optionale Metriken — **S bis M**
+
+Heute: `console.warn`-Prosa. Vorschlag: JSON-Logzeilen hinter `LOG_LEVEL`, plus
+optionales `GET /api/metrics` im Prometheus-Textformat mit Cache-Hit-Rate,
+Immich-Latenz-Histogramm, Rate-Limit-Treffern und Bytes durch den Bild-Proxy.
+
+**Warum es sich lohnt:** Die Self-Hosting-Community betreibt Grafana. Ein
+Projekt, das ein fertiges Dashboard-JSON mitliefert, wirkt sofort erwachsen —
+und es ist wenig Arbeit, weil die Zählpunkte (`lib/cache.ts`, `lib/immich.ts`,
+`lib/rate-limit.ts`) schon zentralisiert sind.
+
+---
+
+### A8. Redis-Backend, aber nur optional — **M, niedrige Priorität**
+
+Rate-Limiter und Cache sind ausdrücklich In-Memory und skalieren nicht über
+mehrere Instanzen. Ein optionales Backend hinter `REDIS_URL` würde das lösen.
+
+**Ehrliche Einschätzung:** Die Zielgruppe fährt einen Container. Das ist
+Dokumentation eines bekannten Limits, kein dringendes Feature. Nur angehen, wenn
+konkret danach gefragt wird.
+
+---
+
+## B. Open-Source-Verbreitung
+
+### B1. Setup-Assistent im Browser statt Anleitung — **M, größter Adoption-Hebel**
+
+**Befund:** `components/SetupScreen.tsx` erklärt dem Nutzer, welche Dateien er
+per Hand kopieren und ausfüllen soll. Gleichzeitig kann das Admin-Panel bereits
+YAML atomar schreiben (`lib/admin/yaml-service.ts`) und alle Immich-Alben
+durchsuchen (`/api/admin/albums`) — die Bausteine für einen echten Assistenten
+liegen also schon da.
+
+**Idee:** Aus dem Setup-Screen einen geführten Ablauf machen:
+
+1. Immich-URL + API-Key eingeben → Verbindung sofort testen, Permissions prüfen
+2. Aus den gefundenen Shared Albums auswählen (visuelle Auswahl, keine UUIDs)
+3. Theme-Preset aus Vorschaukarten wählen (die Screenshots existieren in `docs/screenshots/`)
+4. Titel/Untertitel eintragen → fertig, Galerie steht
+
+Schreibt `gallery.yaml`, `settings.yaml` und die Credentials. Absicherung: nur
+erreichbar, solange `needsSetup` gilt — danach dicht.
+
+**Warum das die wichtigste Einzelmaßnahme ist:** Der Unterschied zwischen
+„funktioniert nach fünf Minuten" und „ich muss erst UUIDs aus der Immich-API
+kopieren" entscheidet, ob jemand dabei bleibt. Immich selbst hat diesen
+Onboarding-Standard gesetzt; Folio wird daran gemessen.
+
+---
+
+### B2. Demo-Modus ohne Immich-Instanz — **S bis M**
+
+**Befund:** Ohne laufenden Immich lässt sich Folio überhaupt nicht ansehen.
+Auch die E2E-Tests (`e2e/`) hängen deshalb an einer echten Instanz.
+
+**Idee:** `DEMO_MODE=true` schaltet `lib/immich.ts` auf einen Fixture-Adapter mit
+mitgelieferten, frei lizenzierten Bildern um. Drei Effekte auf einen Schlag:
+
+- Eine öffentliche Live-Demo, die man im README verlinken kann
+- E2E-Tests laufen deterministisch in CI, ohne Immich
+- Interessenten können `docker run` machen und sofort etwas sehen
+
+**Warum:** Bei Self-Hosted-Software ist die Live-Demo der Konversionspunkt.
+Screenshots im README reichen nicht — Leute wollen durchklicken.
+
+---
+
+### B3. Deploy-Templates für die Kanäle, wo die Zielgruppe sucht — **S**
+
+Docker-Compose ist vorhanden. Was fehlt, sind die Verzeichnisse, in denen
+Immich-Nutzer tatsächlich stöbern: unRAID Community Applications, CasaOS- und
+Umbrel-App-Store, Portainer-Stack, Coolify-/Dokploy-Template.
+
+Wenig Code, überwiegend Metadaten und PRs an fremde Repos. Aber es ist der
+Unterschied zwischen „muss man kennen" und „findet man".
+
+---
+
+### B4. Internationalisierung (DE/EN) — **M**
+
+Steht in der alten Liste, hier aber mit anderer Begründung: nicht als
+Besucher-Komfort, sondern als Verbreitungs-Voraussetzung. Das Projekt hat
+deutsche Wurzeln (`app/impressum/page.tsx`, das `legal:`-Feld ist auf § 18 MStV
+gemünzt), die Oberfläche ist Englisch, und deutsche Nutzer stolpern über den
+Mix. Umgekehrt schreckt ein „Impressum" im Footer internationale Nutzer ab,
+solange nicht klar ist, dass es abschaltbar ist.
+
+**Reihenfolge:** Erst die Besucher-Oberfläche, dann das Admin-Panel. Ohne
+Framework — ein einfacher Wörterbuch-Lookup gegen `settings.yaml: locale`
+genügt und passt zur Vanilla-CSS-/Kein-Framework-Linie des Projekts.
+
+---
+
+### B5. Update-Hinweis im Admin-Dashboard — **XS bis S**
+
+Version aus `package.json` gegen die GitHub-Releases-API prüfen (gecacht,
+täglich, abschaltbar) und im Admin-Dashboard dezent anzeigen. Standard bei
+Self-Hosted-Tools; Nutzer laufen sonst monatelang auf alten Versionen —
+insbesondere problematisch, weil es bereits Security-Releases gab (`37f7f62`).
+
+---
+
+### B6. Themes teilbar machen — **S**
+
+Export/Import von `settings.yaml` als „Theme-Paket" plus ein
+`themes/community/`-Verzeichnis im Repo, in das Nutzer per PR ihre Presets
+beisteuern.
+
+**Warum:** Es schafft einen Beitragsweg für Leute, die kein TypeScript
+schreiben. Fotografen mit Gestaltungsanspruch sind genau die Zielgruppe — und
+jeder eingereichte Look ist zugleich Werbematerial.
+
+---
+
+### B7. Tests für die API-Routen — **M**
+
+`lib/__tests__/` deckt die Bibliotheken gut ab (Tokens, Auth, Rate-Limit,
+Config), `e2e/` deckt fünf Seiten ab. Die Routen selbst — Bild-Proxy,
+Auth-Endpoint, die sieben Admin-Routen — haben keine direkten Tests.
+
+Das ist ausgerechnet die Schicht, an der die Sicherheitsgarantien des Projekts
+hängen: Allowlist-Durchsetzung, Token-Decoding, Rate-Limit-Namespaces,
+Admin-Session-Prüfung. Nach `37f7f62` („fix pre-auth bypasses") sollte hier eine
+Regressions-Suite liegen. Sie ist außerdem das, was Contributors Sicherheit
+gibt, überhaupt PRs zu stellen.
+
+---
+
+### B8. Kleinigkeit: Projektname in `package.json` — **XS**
+
+`"name": "immich-lightbox"` bei einem Projekt namens Immich Folio. Fällt jedem
+Contributor beim ersten `npm install` auf.
+
+---
+
+## C. Ein größerer Differenziator
+
+### C1. Mehrere Galerien aus einer Instanz — **L**
+
+Heute: ein Container, ein Portfolio. Denkbar: mehrere Sites aus einer Instanz,
+je nach Host-Header, mit eigener `gallery.yaml`, eigenem Theme und eigener
+Domain — bei geteiltem Immich-Backend und geteiltem Bild-Cache.
+
+**Zielgruppen:** Fotografen-Kollektive; Leute, die für Kunden hosten; jemand,
+der öffentliches Portfolio und private Familiengalerie trennen will.
+
+**Ehrliche Einschätzung:** Deutlich mehr Aufwand als alles andere hier, weil
+Config-Singleton (`lib/config/index.ts`), Cache-Keys und Auth-Cookie-Namen alle
+mandantenfähig werden müssten. Nur sinnvoll, wenn tatsächlich Nachfrage
+entsteht — aber es wäre etwas, das kein vergleichbares Tool bietet. Als
+Beobachtungsposten notieren, nicht als Plan.
+
+---
+
+## Empfohlene Reihenfolge
+
+**Erst (kleiner Aufwand, sofort sichtbar):**
+
+1. A1 — Fehler-/Lade-/404-Boundaries · _XS_
+2. A6 — `AUTH_SECRET` automatisch bereitstellen · _XS_
+3. B8 — Projektname korrigieren · _XS_
+4. B5 — Update-Hinweis im Admin · _XS–S_
+
+**Dann (die zwei Hebel, die den Unterschied machen):**
+
+5. B1 — Setup-Assistent im Browser · _M_
+6. A2 — Stale-while-error · _M_
+
+**Danach:**
+
+7. A5 — Config-Doctor · _S_
+8. B2 — Demo-Modus · _S–M_
+9. B3 — Deploy-Templates · _S_
+10. A3 — Persistenter Bild-Cache · _M_
+11. B7 — API-Routen-Tests · _M_
+
+**Später / nach Bedarf:** A4 (ISR), A7 (Logs & Metriken), B4 (i18n), B6 (Theme-Sharing),
+A8 (Redis), C1 (Multi-Site).
+
+---
+
+## Roter Faden
+
+Zwei Sätze, die die Auswahl zusammenhalten:
+
+**Verbreitung** entscheidet sich in den ersten fünf Minuten — deshalb
+Setup-Assistent (B1) und Demo-Modus (B2) vor allem anderen.
+
+**Robustheit** heißt bei Folio nicht Uptime der eigenen App, sondern
+Unabhängigkeit von der Verfügbarkeit des privaten Immich — deshalb ist
+Stale-while-error (A2) das strategisch wichtigste Backend-Feature, nicht ISR.
diff --git a/docs/deep-dive-2026-08-05.md b/docs/deep-dive-2026-08-05.md
new file mode 100644
index 0000000..392d92a
--- /dev/null
+++ b/docs/deep-dive-2026-08-05.md
@@ -0,0 +1,364 @@
+# Deep Dive: die vier priorisierten Themen
+
+_Stand: 2026-08-05 · Basis: v0.9.1 · Vertiefung zu [`brainstorm-2026-08-05.md`](brainstorm-2026-08-05.md)_
+
+Vertieft: (1) Fehler-Boundaries, (2) Setup-Assistent, (3) Stale-while-error,
+(4) API-Routen-Tests.
+
+**Vorab drei Korrekturen** an meiner ersten Einschätzung, die sich beim Lesen des
+Codes ergeben haben:
+
+- Ein unerreichbarer Immich führt **nicht** zu einem Absturz. `request()` fängt
+  den Fehler und gibt `null` zurück — die Seite wird still leer und liefert
+  HTTP 404 für real existierende Alben. Das ist ein anderes (und heimtückischeres)
+  Problem als ein Crash.
+- Ein **`app/error.tsx` würde den wichtigsten Fehlerfall gar nicht abfangen**,
+  weil `app/layout.tsx:53` selbst `getConfig()` aufruft. Nötig ist `global-error.tsx`.
+- Der Setup-Assistent hat ein architektonisches Hindernis, das man erst beim
+  Bauen bemerkt: Credentials kommen aus **Env-Variablen**, nicht aus YAML — und
+  `lib/env.ts` parst genau einmal beim Prozessstart.
+
+---
+
+## 1. Fehler-, Lade- und 404-Boundaries
+
+### Befund
+
+Kein `error.tsx`, `global-error.tsx`, `not-found.tsx` oder `loading.tsx` im
+gesamten `app/`-Baum. Es gibt **zwei völlig verschiedene Fehlermodi**, die
+unterschiedliche Antworten brauchen:
+
+**Modus A — die Konfiguration wirft.** `getConfig()` wirft an mehreren Stellen hart:
+
+| Stelle | Auslöser |
+|---|---|
+| `lib/config/index.ts:136` | `gallery.yaml` ohne Album und ohne Subpage |
+| `lib/config/index.ts:144` | Subpage ohne `name` |
+| `lib/config/index.ts:170` | Subpage ohne Alben/Sections |
+| `lib/secret.ts:20` | `AUTH_SECRET` fehlt in Production |
+
+Nicht in dieser Liste: `validateUuid()` (`lib/config/parser.ts`) wirft **nicht** —
+es warnt und liefert bewusst eine Dummy-UUID zurück, damit der Build nicht bricht.
+Eine kaputte Album-ID führt also zu einem stillschweigend fehlenden Album, nicht
+zu einem Fehler. Das ist ein Fall für den Config-Doctor (A5), nicht für die
+Boundaries.
+
+**Modus B — Immich ist nicht erreichbar.** Hier wirft nichts: `request()` fängt
+alles ab (`lib/immich.ts:108–111`) und liefert `null`. Folge:
+
+- `getAlbums()` → `[]` → Startseite zeigt **stillschweigend keine Alben**
+- `getAlbum()` → `null` → `notFound()` (`app/[...path]/page.tsx:233`) →
+  **HTTP 404 für eine URL, die es wirklich gibt**
+- Map, EXIF, OG-Images: leer
+
+### Der entscheidende technische Punkt
+
+`app/error.tsx` wird **innerhalb** des Root-Layouts gerendert. Da das Layout
+selbst `getConfig()` aufruft (`app/layout.tsx:53`), wirft bei Modus A das Layout —
+und ein `error.tsx` kommt nie zum Zug. Nur `app/global-error.tsx` greift, weil es
+`<html>` und `<body>` vollständig ersetzt.
+
+Daraus folgt: `global-error.tsx` muss **komplett eigenständig** sein — eigene
+`<html>`/`<body>`, Inline-Styles, kein `getConfig()`, kein Theme-Zugriff. Genau
+wie der heutige `SetupScreen`, der aus demselben Grund schon inline gestylt ist.
+
+### Entwurf
+
+**`app/global-error.tsx`** — der Konfigurations-Notausgang. Sollte nicht „Etwas ist
+schiefgelaufen" sagen, sondern die Datei nennen, in der das Problem steckt. Die
+Fehlermeldungen aus `getConfig()` sind bereits präzise formuliert
+(`Subpage "Reisen" must have albums or sections`) — sie sind die halbe Miete, sie
+kommen nur nirgends an. In Production nur Dateiname + Meldung zeigen, keine
+Stacktraces.
+
+**`app/error.tsx`** — für Render-Fehler unterhalb des Layouts, im Theme-Look, mit
+`reset()`-Button.
+
+**`app/not-found.tsx`** — gestaltete 404 statt Next.js-Default.
+
+**`loading.tsx` pro Segment** — Skeletons aus ThumbHash (`lib/thumbhash.ts` ist da).
+Wirkt besonders, weil alle Seiten `force-dynamic` sind und heute komplett auf die
+Immich-Antwort warten, bevor irgendetwas erscheint.
+
+### Der Teil, der wirklich zählt: 404 vs. 503
+
+Heute kann die App nicht unterscheiden zwischen „dieses Album existiert nicht"
+und „ich kann Immich gerade nicht fragen". Beides endet in `notFound()`.
+
+Das ist nicht nur kosmetisch: Ein 404 sagt Suchmaschinen *„diese URL löschen"*,
+ein 503 sagt *„später nochmal versuchen"*. Ein Immich-Update während eines
+Google-Crawls kann so die Sichtbarkeit des Portfolios kosten.
+
+**Vorschlag:** Bevor `app/[...path]/page.tsx` `notFound()` aufruft, den
+Upstream-Status prüfen (`immich.ping()` ist über `/api/health` bereits mit
+10-Sekunden-Cache versehen — wiederverwenden, nicht neu bauen). Ist Immich
+unerreichbar, stattdessen werfen → Error-Boundary → 5xx. Das greift direkt in
+Thema 3 über.
+
+### Aufwand
+
+**XS** für die drei Boundary-Dateien. **S**, wenn die 404/503-Unterscheidung
+mitkommt. Ich würde beides zusammen machen — die Boundaries allein sind Kosmetik,
+erst mit der Statusunterscheidung werden sie ein Feature.
+
+---
+
+## 2. Setup-Assistent im Browser
+
+### Befund: das Hindernis
+
+`components/SetupScreen.tsx` erklärt vier Dateikopien und endet mit
+*„restart your server"*. Ein Assistent müsste stattdessen selbst schreiben — und
+stößt sofort auf ein Problem:
+
+```ts
+// lib/env.ts, letzte Zeile
+export const env = parseEnv();   // läuft genau einmal beim Modul-Load
+```
+
+`IMMICH_API_URL` und `IMMICH_API_KEY` kommen aus der Umgebung. Ein Browser-Formular
+kann eine Umgebungsvariable eines laufenden Prozesses nicht ändern. YAML dagegen
+ist bereits heiß nachladbar — `loadYaml()` prüft die mtime, und `getConfig()`
+verzichtet bewusst auf einen In-Memory-Cache (Kommentar in `lib/config/index.ts:49–52`).
+
+Die Credentials liegen also ausgerechnet in der einzigen Schicht, die einen
+Neustart erzwingt.
+
+### Drei Wege
+
+**(a) Assistent schreibt `.env.local`.** Erfordert `docker restart`. Zerstört das
+Versprechen „in fünf Minuten fertig", und in vielen Compose-Setups liegt
+`.env.local` nicht einmal in einem gemounteten Volume — die Datei wäre nach dem
+Neustart weg.
+
+**(b) Credentials nach `content/` verlagern**, z. B. `content/connection.yaml`
+(Mode 0600), gelesen über denselben mtime-Loader. Kein Neustart, Assistent läuft
+durch. Bricht aber bestehende Deployments, wenn Env nicht mehr gilt.
+
+**(c) Hybrid — Empfehlung.** Env gewinnt, wenn gesetzt; sonst Fallback auf
+`content/connection.yaml`. Bestehende Installationen ändern sich um nichts, neue
+Nutzer bekommen den Assistenten. `lib/env.ts` bleibt der alleinige Env-Parser;
+der Fallback gehört nach `lib/config/index.ts`, wo `apiUrl`/`apiKey` ohnehin schon
+aufgelöst werden (Zeilen 53–54). Ein Eingriff, eine Stelle.
+
+### Was schon existiert
+
+Bemerkenswert viel — der Assistent ist eher Verdrahtung als Neubau:
+
+| Baustein | Wo |
+|---|---|
+| `/admin` bleibt während des Setups erreichbar | `app/layout.tsx:68–79`, `isAdminPath()`, Commit `8f0bb94` |
+| Atomares YAML-Schreiben mit Backups | `lib/admin/yaml-service.ts` |
+| Alle Shared Albums listen (ohne Allowlist) | `GET /api/admin/albums` |
+| Visuelle Album-/Asset-Auswahl | `AlbumPicker.tsx`, `AssetPicker.tsx` |
+| Theme-Vorschaubilder | `docs/screenshots/theme-*.png` |
+| Cache nach dem Speichern invalidieren | `invalidateConfigCache()` |
+
+Dass `/admin` während `needsSetup` offen bleibt, wurde in `#392` bewusst gebaut —
+mit genau dieser Begründung („it is the tool that completes the setup").
+
+### Ablauf
+
+1. **Verbinden** — URL + API-Key eingeben, sofort gegen `/server/ping` testen,
+   Permissions prüfen, Immich-Version prüfen (Folio braucht ≥ 3.0, siehe die
+   Warnung in `lib/immich.ts:400`). Fehler hier sofort und verständlich melden —
+   das ist die Stelle, an der die meisten scheitern.
+2. **Alben wählen** — visuell aus den Shared Albums, keine UUIDs.
+3. **Look wählen** — Preset-Karten mit den vorhandenen Screenshots.
+4. **Identität** — Titel, Untertitel, Footer.
+
+Schreibt `connection.yaml`, `gallery.yaml`, `settings.yaml`; ruft
+`invalidateConfigCache()`; leitet auf die fertige Galerie.
+
+### Die Sicherheitsfrage, die vorher beantwortet sein muss
+
+Während `needsSetup` gilt, ist die Instanz frisch — möglicherweise ohne gesetztes
+`ADMIN_PASSWORD`. Ein ungeschützter Assistent auf einer öffentlichen URL bedeutet:
+Wer den Container zuerst findet, besitzt ihn.
+
+Zwei gängige Muster: einmaliges Setup-Token ins Container-Log schreiben (wie es
+diverse Self-Hosted-Tools machen), oder `ADMIN_PASSWORD` zur Voraussetzung machen.
+
+**Empfehlung: `ADMIN_PASSWORD` voraussetzen.** Das Sicherheitsmodell bleibt exakt
+wie heute (`lib/admin/auth.ts`, HMAC-Session-Cookie), es gibt keinen zweiten,
+schwächeren Pfad — und aus Nutzersicht ist es trotzdem ein Fortschritt: **eine**
+Env-Variable statt dreien. Angesichts von Commit `37f7f62` („fix pre-auth
+bypasses") ist zusätzliche Vorsicht in genau diesem Bereich angebracht.
+
+### Aufwand
+
+**M.** Der größte Einzelhebel für Verbreitung — aber erst nach der
+Credentials-Entscheidung (c) sinnvoll anzufangen, weil sie den Rest bestimmt.
+
+---
+
+## 3. Stale-while-error
+
+### Befund: es ist kein Absturz, es ist Stille
+
+Meine ursprüngliche Formulierung war ungenau. `request()` wirft nicht, es gibt
+`null` zurück. Wenn Immich weg ist, passiert Folgendes:
+
+| Aufruf | Ergebnis | Für den Besucher |
+|---|---|---|
+| `getAlbums()` | `[]` | Startseite ohne Alben |
+| `getAlbum(id)` | `null` → `notFound()` | **HTTP 404 auf echter URL** |
+| `getAssetInfo()` | `null` | Kein EXIF, keine Map-Punkte |
+| `/api/image/[id]` | 404 pro Bild | Kaputte Bildplätze |
+
+Immerhin sauber gelöst: das leere Ergebnis wird **nicht** gecacht
+(`lib/immich.ts:214`, `if (!all) return []` steht vor `cache.set`) — es brennt
+sich also nichts ein.
+
+Das eigentliche Problem ist der 404. Eine Portfolio-Seite, die während eines
+Immich-Neustarts gecrawlt wird, meldet Suchmaschinen die Löschung ihrer eigenen
+Alben. Das ist der Grund, warum ich das über ISR stellen würde: Bei ISR geht es um
+Millisekunden, hier geht es um Auffindbarkeit.
+
+### Entwurf — drei kleine Eingriffe
+
+**1. `lib/cache.ts`: abgelaufene Einträge behalten.**
+Heute löscht `get()` beim Ablauf (Zeilen 23–26). Stattdessen zwei Zeitstempel pro
+Eintrag — `staleAt` (bisheriges TTL) und `hardExpiresAt` — und ein neues
+`getStale<T>(key)`, das auch abgelaufene Daten herausgibt. Die Speichergrenze
+regelt weiterhin die LRU-Eviction. Ein hartes Limit (`STALE_MAX_AGE`, Default 24 h)
+verhindert, dass ein dauerhaft totes Immich wochenalte Daten ausliefert.
+
+**2. `lib/immich.ts`: Fallback statt Leere.**
+In `getAlbums()`, `getAlbum()` und `getAssetInfo()` bei `null` aus `request()`
+zuerst `cache.getStale()` versuchen. Die Rückgabe sollte mitführen, ob die Daten
+frisch oder stale sind — sonst kann die Seite es nicht anzeigen.
+
+**3. Konsequenz ziehen: nicht `notFound()`, wenn der Upstream tot ist.**
+Gibt es weder frische noch stale Daten *und* ist Immich nachweislich unerreichbar,
+dann werfen statt 404. Das ist derselbe Eingriff wie in Thema 1 — die beiden
+Punkte sind eigentlich ein Feature von zwei Seiten. Den Ping nicht neu bauen:
+`app/api/health/route.ts` hat bereits einen 10-Sekunden-gecachten, gegen
+Thundering-Herd abgesicherten `immich.ping()`; den Mechanismus in ein kleines
+Modul ziehen und beidseitig nutzen.
+
+### Trade-offs, die benannt gehören
+
+- **Stale kann falsch sein.** Ein in Immich gelöschtes Foto bliebe bis zu
+  `STALE_MAX_AGE` sichtbar. Für ein kuratiertes Portfolio ist das Risiko gering,
+  aber es ist eine bewusste Entscheidung, keine Nebenwirkung.
+- **Passwörter sind nicht betroffen.** Sie stammen aus `gallery.yaml`, nicht aus
+  Immich — eine Passwortänderung greift also sofort, unabhängig vom Stale-Cache.
+  Das ist der beruhigende Teil.
+- **Nur im Prozessspeicher.** Nach einem Container-Neustart ist der Cache leer,
+  ein gleichzeitig totes Immich hilft dann nicht. Der persistente Bild-Cache
+  (A3 im Brainstorm) ist die natürliche Fortsetzung — zusammen überleben die
+  beiden auch einen Neustart.
+
+### Aufwand
+
+**M.** Die Cache-Änderung selbst ist klein; die Sorgfalt steckt in der
+404/503-Politik und darin, den Stale-Zustand ehrlich anzuzeigen.
+
+---
+
+## 4. Tests für die API-Routen
+
+### Befund: strukturell ausgeschlossen
+
+```ts
+// vitest.config.ts
+include: ['lib/__tests__/**/*.test.ts'],
+```
+
+Die Routen sind nicht vergessen worden — sie sind per Konfiguration außen vor.
+Das ist eine Einzeilenänderung.
+
+Und die Infrastruktur passt bereits:
+
+- `environment: 'node'` — Route-Handler sind gewöhnliche async-Funktionen, die
+  ein `NextRequest` nehmen. `new NextRequest('http://localhost/api/image/xyz')`
+  genügt, es braucht keinen laufenden Server.
+- `vitest.setup.ts` setzt die Pflicht-Env inklusive `AUTH_SECRET`.
+- `lib/__tests__/immich.test.ts` zeigt das Muster: `vi.mock('../config')` plus
+  `global.fetch = vi.fn()`. Exakt das, was Routentests brauchen.
+
+Der Einstieg ist also billiger, als es aussieht.
+
+### Was zu testen sich lohnt — Invarianten, keine Zeilen
+
+**Allowlist.** `getAlbum()` weist nicht gelistete IDs ab (`lib/immich.ts:374`).
+Ein Album aus `gallery.yaml` entfernen → Route muss 404 liefern.
+
+**Token-Grenze.** `/api/image/[id]` mit roher UUID statt Token → 400. Mit einem
+Token, das unter einem *anderen* `AUTH_SECRET` erzeugt wurde → 400. `tokens.ts`
+ist unit-getestet; hier geht es darum, dass die *Route* das durchsetzt.
+
+**Die Lücke, die dokumentiert gehört.** Der Bild-Proxy dekodiert den Token und
+streamt (`app/api/image/[id]/route.ts:78`) — er prüft **nicht**, ob das Asset noch
+zu einem freigegebenen Album gehört. Da Tokens deterministisch sind (bewusst, für
+Browser-Caching, siehe `CLAUDE.md`), folgt daraus: **Ein Album aus `gallery.yaml`
+zu entfernen widerruft bereits ausgelieferte Bild-URLs nicht.** Sie funktionieren
+weiter, solange `AUTH_SECRET` gleich bleibt.
+
+Das ist ein legitimer Trade-off, aber ein überraschender. Er verdient einen Test,
+der das Verhalten festschreibt, und eine Zeile im README — sonst nimmt jemand an,
+„nicht mehr veröffentlicht" hieße „nicht mehr erreichbar".
+
+**Content-Type-Sanitisierung.** Zeilen 84–93 der Bild-Route stammen aus einem
+echten Stored-XSS-Fix (`c2fa8e7`). `image/svg+xml` und `text/xml` müssen zu
+`application/octet-stream` werden. Klassischer Regressionskandidat.
+
+**Rate-Limit-Namespaces.** Die Buckets sind pro Endpunkt getrennt (`image:`,
+`map:`, `auth:`). Test: `image:` ausschöpfen darf `/api/auth` nicht auf 429 setzen.
+
+**Admin-Guards — der wertvollste Einzeltest.** Alle sieben `/api/admin/*`-Routen
+müssen ohne gültiges Session-Cookie ablehnen, ebenso mit einem unter falschem
+Secret signierten Token. Das ist genau die Fläche von Commit `37f7f62`.
+
+Entscheidend ist die Bauform: **tabellengetrieben über die Liste der
+Admin-Routen**, nicht sieben Einzeltests. Dann schlägt die Suite auch bei einer
+*künftig hinzugefügten* Route ohne Guard an — sie testet dann die Regel statt der
+sieben bekannten Fälle. Das ist der Unterschied zwischen einer Suite, die alte
+Bugs festhält, und einer, die neue verhindert.
+
+**Passwort-Gate.** `/api/auth` setzt das Cookie nur bei korrektem Passwort;
+Vergleich zeitkonstant; die drei Pfade `scrypt:` / Klartext / abgelehntes bcrypt.
+
+**304/ETag.** Bei `If-None-Match` kein Body.
+
+### Aufwand
+
+**M** für die volle Abdeckung. Aber der Einstieg ist klein: `vitest.config.ts`
+erweitern, dann Admin-Guard-Tabelle und Content-Type-Regression zuerst — das ist
+etwa ein halber Tag und deckt bereits beide Stellen ab, an denen es in der
+Vergangenheit real geknallt hat.
+
+---
+
+## Reihenfolge und Zusammenhänge
+
+Die vier Themen sind nicht unabhängig:
+
+```
+Thema 1 (Boundaries)  ─┐
+                       ├─→ gemeinsame 404-vs-503-Politik
+Thema 3 (Stale)       ─┘
+
+Thema 2 (Assistent)   ──→ hängt an der Credentials-Entscheidung (c)
+
+Thema 4 (Tests)       ──→ sichert 1–3 ab, sollte parallel mitlaufen
+```
+
+**Phase 1 — etwa ein Tag, sofort sichtbar**
+`global-error.tsx`, `error.tsx`, `not-found.tsx`, `loading.tsx`;
+`vitest.config.ts` erweitern; Admin-Guard-Tabellentest.
+
+**Phase 2 — die Betriebs-Härtung**
+Stale-Cache plus 404/503-Politik. Ein Vorhaben, nicht zwei. Danach die
+Content-Type- und Allowlist-Tests nachziehen.
+
+**Phase 3 — der Verbreitungs-Hebel**
+Setup-Assistent, beginnend mit dem Hybrid-Fallback für Credentials und der
+Entscheidung, `ADMIN_PASSWORD` vorauszusetzen.
+
+### Der eine Satz dahinter
+
+Phase 1 und 2 sorgen dafür, dass die Seite eines fremden Fotografen auch dann
+noch etwas Vernünftiges tut, wenn dessen Immich hustet — und Phase 3 sorgt dafür,
+dass dieser Fotograf überhaupt erst so weit kommt.
diff --git a/docs/gallery-config.md b/docs/gallery-config.md
index a303bde..19428d0 100644
--- a/docs/gallery-config.md
+++ b/docs/gallery-config.md
@@ -196,17 +196,17 @@ Your bio text here. Supports full Markdown.
 
 - **Album UUIDs**: In Immich, go to Albums → click an album → the UUID is in the URL bar
 - **Asset UUIDs**: Click any photo → the UUID is in the URL bar
- 
+
 ## System & Security
- 
+
 Advanced system settings are configured via environment variables in your `.env` or `.env.local` file.
- 
+
 ### Rate Limiting
- 
+
 To protect against brute-force attacks and resource exhaustion, Immich Folio includes an in-memory rate limiter.
- 
+
 - `RATE_LIMIT_RPM`: Maximum requests per minute per IP (default: `1500` for general API, `120` for map data).
- 
+
 ### Trusted Proxies
 
 If you run Immich Folio behind a reverse proxy (nginx, Traefik, Caddy, Cloudflare), tell it how many proxies sit in front. Without this, the rate limiter reads a client-supplied header and an attacker can pick their own bucket — defeating brute-force protection on the password endpoints.
@@ -237,8 +237,14 @@ location / {
 }
 ```
 
-`$proxy_add_x_forwarded_for` is the important one: it *appends* the real peer address rather than overwriting the header.
+`$proxy_add_x_forwarded_for` is the important one: it _appends_ the real peer address rather than overwriting the header.
 
 #### Migrating from `TRUSTED_PROXIES`
 
 `TRUSTED_PROXIES` has been removed. It matched proxy IPs against the socket peer address, which a self-hosted Next.js server never exposes — so the check never passed. Setting it silently put **every visitor into one shared rate-limit bucket**, letting a single client trip the limit for the entire site. If it is still set, the app assumes `TRUSTED_PROXY_HOPS=1` and logs a warning; replace it with an explicit value.
+
+### Image Token Revocation
+
+Asset tokens are deterministic — the same photo always yields the same token, which is what lets browsers cache images for a year. The image proxy validates the token but does not re-check album membership on every request.
+
+Removing an album from `gallery.yaml` hides it from the site, but any image URL already handed out (bookmarked, embedded, cached by a browser) keeps working. To invalidate previously issued links, rotate `AUTH_SECRET` — this also signs out every password-protected gallery and admin session.
diff --git a/docs/superpowers/plans/2026-08-05-resilience-boundaries.md b/docs/superpowers/plans/2026-08-05-resilience-boundaries.md
new file mode 100644
index 0000000..d594e35
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-05-resilience-boundaries.md
@@ -0,0 +1,1154 @@
+# Resilience Follow-Up Implementation Plan (v2, gegen v0.9.2)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Die drei Lücken schließen, die nach v0.9.2 aus dem ursprünglichen Resilience-Plan übrig sind: Route-Handler testbar machen und die untestbar gebliebene Sicherheitslogik abdecken, bei Immich-Ausfall die zuletzt bekannten Alben weiter ausliefern, und dynamische Seiten sofort eine Hülle rendern statt einer leeren Seite.
+
+**Architecture:** Drei unabhängige, klein geschnittene Eingriffe. (1) `vitest.config.ts` nimmt Tests unter `app/` auf; darauf aufbauend Tests gegen die Admin-Guards und die Content-Type-Sanitisierung des Bild-Proxys, die beide nur auf Routenebene prüfbar sind. (2) `lib/cache.ts` behält abgelaufene Einträge bis zu einer harten Obergrenze; `lib/immich.ts` fängt den in v0.9.2 eingeführten `ImmichUnavailableError` ab und greift auf diese Daten zurück, bevor es den Fehler weiterreicht. (3) `loading.tsx` liefert Skeletons.
+
+**Tech Stack:** Next.js 16 (App Router, React 19), TypeScript strict, Vitest 4 (node environment), Vanilla CSS, keine neuen Laufzeit-Dependencies.
+
+---
+
+## Was v0.9.2 bereits erledigt hat
+
+Der ursprüngliche Plan (v1) entstand gegen v0.9.1. PR #394 hat davon einen großen Teil umgesetzt — teils anders und besser als geplant. Ersatzlos gestrichen:
+
+| Ehemalige Task | Status in v0.9.2 |
+|---|---|
+| Upstream-Statusmodul (`lib/upstream.ts`) | **Überholt.** Statt eines Seiten-Pings unterscheidet `request()` jetzt an der Quelle: `ImmichUnavailableError` für Ausfälle, `null` nur für 404/410. Das ist die bessere Lösung — kein Nebenkanal, keine Race zwischen Ping und Abruf. |
+| 404-vs-503-Politik in `app/[...path]/page.tsx` | **Erledigt.** Der Fehler propagiert, Seiten liefern 5xx statt 404. Zusätzlich geben `/api/exif` und `/api/map` 503 mit `Retry-After`. |
+| `app/error.tsx`, `app/not-found.tsx` | **Erledigt**, mit `.empty-state` aus `globals.css` und 8 Tests in `lib/__tests__/error-pages.test.ts`. |
+| `app/global-error.tsx` | **Nicht mehr nötig.** Das Layout wirft nicht mehr: `getConfigOrNull()` (`lib/config/index.ts:39`) fängt ab und rendert den SetupScreen, wobei `/admin` erreichbar bleibt. Das war der einzige konkrete Anlass für die Boundary. |
+| Bild-Größen-Tiers | **Erledigt**, nach `lib/imageSize.ts` ausgelagert und getestet. |
+
+Obendrein neu und relevant: `IMMICH_TIMEOUT_MS`, ein `MISSING`-Sentinel, der definitive 404-Antworten cacht, `middleware.ts` → `proxy.ts`, sowie 210 statt 98 Unit-Tests.
+
+**Was das für Task 1 bedeutet:** Die vitest-Grenze wurde in #394 zweimal *umgangen* statt gehoben — `lib/imageSize.ts` wurde eigens ausgelagert, damit die Größenlogik aus `lib/__tests__/` erreichbar ist, und `error-pages.test.ts` benutzt `createElement` statt JSX, weil eine `.tsx`-Datei dort nie ausgeführt würde (so im Commit-Text vermerkt). Die Sicherheitslogik, die sich nicht auslagern lässt — Admin-Guards und Content-Type-Sanitisierung — ist deshalb weiterhin ungetestet.
+
+## Global Constraints
+
+- **Keine neuen Runtime-Dependencies.**
+- **TypeScript strict** — kein untypisiertes `any`; Suppressions nur als `@ts-expect-error` mit Begründung.
+- **Rohe Immich-UUIDs dürfen nie im Client-HTML/JS landen.**
+- **Vanilla CSS**, Tokens aus `app/tokens.css` (`--bg-secondary`, `--radius-sm`, `--grid-columns`, `--grid-gap`, `--grid-aspect-ratio`).
+- **Formatierung:** nur geänderte Dateien (`npx prettier --write <datei>`), nie `npm run format` im Repo-Root.
+- **Vor jedem Commit grün:** `npm run test:unit`, `npx tsc --noEmit`, `npm run lint`.
+- **Baseline vor Beginn:** 210 Tests in 19 Dateien. Jede Task nennt die erwartete neue Summe.
+- **Commit-Stil:** Conventional Commits.
+- **Neue Env-Variablen** gehören in `lib/env.ts` **und** `.env.local.example`.
+
+---
+
+## File Structure
+
+**Neu:**
+
+| Datei | Verantwortung |
+|---|---|
+| `app/api/admin/__tests__/admin-guards.test.ts` | Tabellengetrieben: jede Admin-Route lehnt ohne Session ab. |
+| `app/api/image/__tests__/image-route.test.ts` | Token-Grenze, Content-Type-Sanitisierung, ETag/304. |
+| `lib/__tests__/cache-stale.test.ts` | Stale-Fenster und harte Obergrenze des Caches. |
+| `app/loading.tsx` | Skeleton für die Startseite. |
+| `app/[...path]/loading.tsx` | Skeleton für Album-/Subpage-Routen. |
+| `app/loading.module.css` | Skeleton-Styles. |
+
+**Geändert:**
+
+| Datei | Änderung |
+|---|---|
+| `vitest.config.ts` | `include` um `app/**/__tests__/**/*.test.ts` erweitern. |
+| `lib/cache.ts` | Zwei Deadlines pro Eintrag, `getStale()`. |
+| `lib/immich.ts` | `ImmichUnavailableError` abfangen, Stale-Fallback, sonst weiterwerfen. |
+| `lib/env.ts`, `.env.local.example` | `STALE_MAX_AGE`. |
+| `lib/config/schema.ts`, `lib/config/index.ts` | `staleMaxAge` in `AppConfig` und beide Rückgabepfade. |
+| `README.md`, `CLAUDE.md` | Stale-Verhalten und Token-Widerruf dokumentieren. |
+
+**Abhängigkeiten:**
+
+```
+Task 1 (vitest include + Route-Tests)  ── zuerst, schaltet Tests unter app/ ein
+Task 2 (Stale-while-error)             ── unabhängig von Task 1
+Task 3 (Loading-Skeletons)             ── unabhängig
+Task 4 (Doku)                          ── nach Task 2
+```
+
+---
+
+## Task 1: Route-Handler testbar machen und Sicherheitslogik abdecken
+
+**Warum:** `vitest.config.ts` schließt alles außerhalb von `lib/__tests__/` aus. Zwei Stellen sind deshalb ungetestet und lassen sich auch nicht auslagern: die Guards der acht Admin-Routen und die Content-Type-Normalisierung in `app/api/image/[id]/route.ts:99-107`, die aus einem Stored-XSS-Fix stammt (`c2fa8e7`).
+
+**Erwartungshaltung:** Beide Mechanismen funktionieren heute korrekt. Diese Tests finden keinen Bug — sie sind Regressionsbremsen. Der Wert der Admin-Tabelle liegt darin, dass eine *künftig* ergänzte Route ohne Guard die Suite rot macht.
+
+**Files:**
+- Modify: `vitest.config.ts`
+- Create: `app/api/admin/__tests__/admin-guards.test.ts`
+- Create: `app/api/image/__tests__/image-route.test.ts`
+
+**Interfaces:**
+- Consumes: `isAdminAuthenticated()`, `isAdminEnabled()` (`lib/admin/auth.ts`, gemockt); `encodeAssetId()` (`lib/tokens.ts`); `immich.streamAsset()` (gemockt).
+- Produces: nichts für spätere Tasks.
+
+- [ ] **Step 1: `vitest.config.ts` erweitern**
+
+Die `include`-Zeile in `test` ersetzen:
+
+```ts
+    include: ['lib/__tests__/**/*.test.ts', 'app/**/__tests__/**/*.test.ts'],
+```
+
+- [ ] **Step 2: Prüfen, dass die Baseline unverändert läuft**
+
+Run: `npm run test:unit`
+Erwartung: weiterhin 210 Tests in 19 Dateien — die Erweiterung findet noch keine neuen Dateien.
+
+- [ ] **Step 3: Admin-Guard-Test schreiben**
+
+Erstelle `app/api/admin/__tests__/admin-guards.test.ts`.
+
+Hintergrund: `isAdminAuthenticated()` liest `cookies()` aus `next/headers`, was außerhalb eines Requests wirft. Statt `next/headers` zu mocken, mocken wir `@/lib/admin/auth` — das ist die Schnittstelle, deren Einhaltung geprüft wird. `lib/__tests__/immich.test.ts` nutzt dasselbe `vi.mock`-Muster.
+
+```ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('@/lib/admin/auth', () => ({
+  isAdminEnabled: vi.fn(),
+  isAdminAuthenticated: vi.fn(),
+  COOKIE_NAME: 'folio_admin_session',
+}));
+
+import { isAdminEnabled, isAdminAuthenticated } from '@/lib/admin/auth';
+
+const mockEnabled = isAdminEnabled as unknown as ReturnType<typeof vi.fn>;
+const mockAuthed = isAdminAuthenticated as unknown as ReturnType<typeof vi.fn>;
+
+/**
+ * Every guarded admin route handler. Adding a new /api/admin route means
+ * adding a row here — a route that forgets its guard then fails this suite
+ * instead of shipping. /api/admin/auth is deliberately absent: it is the login
+ * endpoint and must stay reachable without a session.
+ */
+const ROUTES: {
+  name: string;
+  path: string;
+  load: () => Promise<Record<string, unknown>>;
+  method: 'GET' | 'PUT' | 'POST' | 'DELETE';
+  args: () => unknown[];
+}[] = [
+  {
+    name: 'GET /api/admin/gallery',
+    path: 'gallery',
+    load: () => import('../gallery/route'),
+    method: 'GET',
+    args: () => [],
+  },
+  {
+    name: 'PUT /api/admin/gallery',
+    path: 'gallery',
+    load: () => import('../gallery/route'),
+    method: 'PUT',
+    args: () => [new Request('http://localhost/api/admin/gallery', { method: 'PUT', body: '{}' })],
+  },
+  {
+    name: 'GET /api/admin/settings',
+    path: 'settings',
+    load: () => import('../settings/route'),
+    method: 'GET',
+    args: () => [],
+  },
+  {
+    name: 'PUT /api/admin/settings',
+    path: 'settings',
+    load: () => import('../settings/route'),
+    method: 'PUT',
+    args: () => [new Request('http://localhost/api/admin/settings', { method: 'PUT', body: '{}' })],
+  },
+  {
+    name: 'GET /api/admin/albums',
+    path: 'albums',
+    load: () => import('../albums/route'),
+    method: 'GET',
+    args: () => [],
+  },
+  {
+    name: 'POST /api/admin/reload',
+    path: 'reload',
+    load: () => import('../reload/route'),
+    method: 'POST',
+    args: () => [],
+  },
+  {
+    name: 'GET /api/admin/status',
+    path: 'status',
+    load: () => import('../status/route'),
+    method: 'GET',
+    args: () => [],
+  },
+  {
+    name: 'GET /api/admin/assets',
+    path: 'assets',
+    load: () => import('../assets/route'),
+    method: 'GET',
+    args: () => [new Request('http://localhost/api/admin/assets')],
+  },
+  {
+    name: 'GET /api/admin/thumbnail/[id]',
+    path: 'thumbnail/[id]',
+    load: () => import('../thumbnail/[id]/route'),
+    method: 'GET',
+    args: () => [
+      new Request('http://localhost/api/admin/thumbnail/abc'),
+      { params: Promise.resolve({ id: 'abc' }) },
+    ],
+  },
+  {
+    name: 'GET /api/admin/albums/[albumId]/assets',
+    path: 'albums/[albumId]/assets',
+    load: () => import('../albums/[albumId]/assets/route'),
+    method: 'GET',
+    args: () => [
+      new Request('http://localhost/api/admin/albums/a1/assets'),
+      { params: Promise.resolve({ albumId: 'a1' }) },
+    ],
+  },
+];
+
+describe('admin route guards', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  for (const route of ROUTES) {
+    it(`${route.name} returns 403 when the admin panel is disabled`, async () => {
+      mockEnabled.mockReturnValue(false);
+      mockAuthed.mockResolvedValue(false);
+
+      const mod = await route.load();
+      const handler = mod[route.method] as (...a: unknown[]) => Promise<Response>;
+      const res = await handler(...route.args());
+
+      expect(res.status).toBe(403);
+    });
+
+    it(`${route.name} returns 401 without a valid session`, async () => {
+      mockEnabled.mockReturnValue(true);
+      mockAuthed.mockResolvedValue(false);
+
+      const mod = await route.load();
+      const handler = mod[route.method] as (...a: unknown[]) => Promise<Response>;
+      const res = await handler(...route.args());
+
+      expect(res.status).toBe(401);
+    });
+  }
+
+  it('has a row for every route module under app/api/admin', async () => {
+    const fs = await import('fs');
+    const path = await import('path');
+    const adminDir = path.join(process.cwd(), 'app/api/admin');
+
+    const found: string[] = [];
+    const walk = (dir: string) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (entry.name === '__tests__') continue;
+          walk(full);
+        } else if (entry.name === 'route.ts') {
+          found.push(path.relative(adminDir, path.dirname(full)));
+        }
+      }
+    };
+    walk(adminDir);
+
+    const covered = new Set(ROUTES.map((r) => r.path));
+    const uncovered = found.filter((p) => p !== 'auth' && !covered.has(p));
+
+    expect(uncovered, `Admin routes with no guard test: ${uncovered.join(', ')}`).toEqual([]);
+  });
+});
+```
+
+- [ ] **Step 4: Admin-Test laufen lassen**
+
+Run: `npm run test:unit -- app/api/admin/__tests__/admin-guards.test.ts`
+Erwartung: 21 Tests PASS (10 Routen × 2 plus der Abdeckungstest).
+
+Schlägt der Abdeckungstest fehl, nennt die Meldung die fehlenden Pfade — dann die entsprechende Zeile in `ROUTES` ergänzen.
+
+- [ ] **Step 5: Beweisen, dass der Guard-Test greift**
+
+In `app/api/admin/status/route.ts` die beiden Guard-Blöcke vorübergehend auskommentieren.
+
+Run: `npm run test:unit -- app/api/admin/__tests__/admin-guards.test.ts`
+Erwartung: die zwei `GET /api/admin/status`-Tests schlagen fehl.
+
+Auskommentierung rückgängig machen, erneut laufen lassen. Erwartung: alles grün.
+
+- [ ] **Step 6: Bild-Proxy-Test schreiben**
+
+Erstelle `app/api/image/__tests__/image-route.test.ts`:
+
+```ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { NextRequest } from 'next/server';
+import { GET } from '../[id]/route';
+import { encodeAssetId } from '@/lib/tokens';
+import { immich } from '@/lib/immich';
+
+vi.mock('@/lib/immich', async () => {
+  const actual = await vi.importActual<typeof import('@/lib/immich')>('@/lib/immich');
+  return {
+    // Keep the real error class — the route branches on it.
+    ImmichUnavailableError: actual.ImmichUnavailableError,
+    immich: { streamAsset: vi.fn() },
+  };
+});
+
+const mockStream = immich.streamAsset as unknown as ReturnType<typeof vi.fn>;
+
+const ASSET_ID = '11111111-2222-3333-4444-555555555555';
+
+/** Stream stub — the route only forwards the body, it never reads it. */
+function fakeBody(contentType: string) {
+  return {
+    stream: new ReadableStream({
+      start(controller) {
+        controller.enqueue(new Uint8Array([1, 2, 3]));
+        controller.close();
+      },
+    }),
+    contentType,
+    contentLength: '3',
+  };
+}
+
+function call(token: string, query = '', headers?: Record<string, string>) {
+  const req = new NextRequest(`http://localhost/api/image/${token}${query}`, { headers });
+  return GET(req, { params: Promise.resolve({ id: token }) });
+}
+
+describe('GET /api/image/[id]', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('rejects a raw Immich UUID instead of an encoded token', async () => {
+    const res = await call(ASSET_ID);
+    expect(res.status).toBe(400);
+    expect(mockStream).not.toHaveBeenCalled();
+  });
+
+  it('rejects a syntactically broken token', async () => {
+    const res = await call('v2:not-valid-base64url!!');
+    expect(res.status).toBe(400);
+    expect(mockStream).not.toHaveBeenCalled();
+  });
+
+  it('serves a valid token', async () => {
+    mockStream.mockResolvedValue(fakeBody('image/jpeg'));
+    const res = await call(encodeAssetId(ASSET_ID));
+    expect(res.status).toBe(200);
+    expect(mockStream).toHaveBeenCalledWith(ASSET_ID, 'preview');
+  });
+
+  // Regression guard for the stored-XSS fix in c2fa8e7. An SVG served as
+  // image/svg+xml executes script in the browser under our own origin.
+  // This logic lives in the route and cannot be extracted the way
+  // lib/imageSize.ts was, so a route-level test is the only way to pin it.
+  it.each([
+    ['image/svg+xml', 'application/octet-stream'],
+    ['text/xml', 'application/octet-stream'],
+    ['text/html', 'application/octet-stream'],
+    ['application/octet-stream', 'image/jpeg'],
+    ['image/jpeg', 'image/jpeg'],
+    ['image/webp', 'image/webp'],
+  ])('rewrites upstream Content-Type %s to %s', async (upstream, expected) => {
+    mockStream.mockResolvedValue(fakeBody(upstream));
+    const res = await call(encodeAssetId(ASSET_ID));
+    expect(res.headers.get('Content-Type')).toBe(expected);
+  });
+
+  it('returns 304 with no body when the ETag matches', async () => {
+    mockStream.mockResolvedValue(fakeBody('image/jpeg'));
+    const token = encodeAssetId(ASSET_ID);
+
+    const first = await call(token);
+    const etag = first.headers.get('ETag');
+    expect(etag).toBeTruthy();
+
+    const res = await call(token, '', { 'if-none-match': etag as string });
+    expect(res.status).toBe(304);
+    expect(await res.text()).toBe('');
+  });
+
+  it('never leaks the raw asset UUID in response headers', async () => {
+    mockStream.mockResolvedValue(fakeBody('image/jpeg'));
+    const res = await call(encodeAssetId(ASSET_ID));
+    const headerDump = JSON.stringify([...res.headers.entries()]);
+    expect(headerDump).not.toContain(ASSET_ID);
+  });
+
+  it('404s when the asset is genuinely gone', async () => {
+    mockStream.mockResolvedValue(null);
+    const res = await call(encodeAssetId(ASSET_ID));
+    expect(res.status).toBe(404);
+    expect(res.headers.get('Cache-Control')).toBe('no-store');
+  });
+
+  it('503s when Immich is unavailable, and does not let it be cached', async () => {
+    const { ImmichUnavailableError } = await import('@/lib/immich');
+    mockStream.mockRejectedValue(new ImmichUnavailableError('upstream down'));
+    const res = await call(encodeAssetId(ASSET_ID));
+    expect(res.status).toBe(503);
+    expect(res.headers.get('Cache-Control')).toBe('no-store');
+    expect(res.headers.get('Retry-After')).toBeTruthy();
+  });
+});
+```
+
+- [ ] **Step 7: Bild-Test laufen lassen**
+
+Run: `npm run test:unit -- app/api/image/__tests__/image-route.test.ts`
+Erwartung: 12 Tests PASS.
+
+Zwei mögliche Stolperstellen — beide zuerst gegen den Code prüfen, bevor der Test angepasst wird:
+- Falls der Rate-Limiter über die Aufrufe hinweg greift, in `vitest.setup.ts` `process.env.RATE_LIMIT_RPM = '100000'` ergänzen.
+- Falls die 503-Header anders heißen als erwartet, den tatsächlichen Wert aus `app/api/image/[id]/route.ts` übernehmen — der Test soll das reale Verhalten festschreiben.
+
+- [ ] **Step 8: Beweisen, dass der XSS-Test greift**
+
+In `app/api/image/[id]/route.ts` die Normalisierung vorübergehend durch `const contentType = result.contentType.toLowerCase();` ersetzen und die nachfolgenden `if`-Blöcke auskommentieren.
+
+Run: `npm run test:unit -- app/api/image/__tests__/image-route.test.ts`
+Erwartung: die Fälle `image/svg+xml`, `text/xml`, `text/html`, `application/octet-stream` schlagen fehl.
+
+Änderung rückgängig machen. Erwartung: alles grün.
+
+- [ ] **Step 9: Gesamtprüfung**
+
+Run: `npm run test:unit`
+Erwartung: 243 Tests in 21 Dateien (210 + 21 + 12).
+
+Run: `npx tsc --noEmit`
+Erwartung: 0 Fehler.
+
+Run: `npm run lint`
+Erwartung: 0 Fehler.
+
+- [ ] **Step 10: Commit**
+
+```bash
+npx prettier --write vitest.config.ts app/api/admin/__tests__/admin-guards.test.ts app/api/image/__tests__/image-route.test.ts
+git add vitest.config.ts app/api/admin/__tests__/admin-guards.test.ts app/api/image/__tests__/image-route.test.ts
+git commit -m "test: enable route-handler tests and cover admin guards and image content-type"
+```
+
+---
+
+## Task 2: Stale-while-error
+
+**Warum:** v0.9.2 unterscheidet Ausfall und Nichtexistenz sauber und liefert bei Ausfall 5xx statt 404 — das war die dringendere Hälfte. Die andere Hälfte fehlt: Ein Besucher sieht während eines Immich-Neustarts eine Fehlerseite, obwohl die Alben Sekunden zuvor noch im Speicher lagen. `lib/cache.ts` löscht abgelaufene Einträge beim Zugriff (Zeile 23).
+
+**Wichtig zur Abgrenzung:** v0.9.2 cacht Ausfälle bewusst *nicht* — ein `ImmichUnavailableError` wird nie gespeichert, damit die Galerie nach der Erholung nicht kaputt bleibt. Diese Task ändert daran nichts. Sie sorgt nur dafür, dass ein früherer **Erfolg** länger verfügbar bleibt, als seine TTL erlaubt. Beides zusammen ergibt: Ausfälle werden nicht eingebrannt, Erfolge überdauern sie.
+
+**Files:**
+- Modify: `lib/cache.ts`
+- Create: `lib/__tests__/cache-stale.test.ts`
+- Modify: `lib/env.ts`, `.env.local.example`
+- Modify: `lib/config/schema.ts`, `lib/config/index.ts`
+- Modify: `lib/immich.ts`, `lib/__tests__/immich.test.ts`
+
+**Interfaces:**
+- Consumes: `ImmichUnavailableError` aus `lib/immich.ts` (in v0.9.2 eingeführt, Zeile 97).
+- Produces:
+  - `cache.get<T>(key): T | null` — unverändert, nur frische Daten.
+  - `cache.getStale<T>(key): T | null` — auch abgelaufene, solange die harte Obergrenze hält.
+  - `cache.set<T>(key, data, ttlMs, staleMaxAgeMs?)` — vierter Parameter optional, Default 24 h.
+  - `AppConfig.staleMaxAge: number` (Millisekunden).
+
+- [ ] **Step 1: Cache-Test schreiben**
+
+Erstelle `lib/__tests__/cache-stale.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { cache } from '../cache';
+
+describe('MemoryCache stale window', () => {
+  beforeEach(() => {
+    cache.clear();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('returns fresh entries from get()', () => {
+    cache.set('k', { v: 1 }, 1000);
+    expect(cache.get<{ v: number }>('k')).toEqual({ v: 1 });
+  });
+
+  it('returns null from get() once the ttl elapsed', () => {
+    cache.set('k', { v: 1 }, 1000);
+    vi.advanceTimersByTime(1001);
+    expect(cache.get('k')).toBeNull();
+  });
+
+  it('still returns the value from getStale() after the ttl elapsed', () => {
+    cache.set('k', { v: 1 }, 1000, 60_000);
+    vi.advanceTimersByTime(1001);
+    expect(cache.getStale<{ v: number }>('k')).toEqual({ v: 1 });
+  });
+
+  it('drops the entry from getStale() past the hard max age', () => {
+    cache.set('k', { v: 1 }, 1000, 5000);
+    vi.advanceTimersByTime(5001);
+    expect(cache.getStale('k')).toBeNull();
+  });
+
+  it('does not let get() destroy the stale fallback', () => {
+    // get() must not delete an expired entry — otherwise the fallback is gone
+    // the moment any caller asks for fresh data first.
+    cache.set('k', { v: 1 }, 1000, 60_000);
+    vi.advanceTimersByTime(1001);
+    expect(cache.get('k')).toBeNull();
+    expect(cache.getStale<{ v: number }>('k')).toEqual({ v: 1 });
+  });
+
+  it('never expires stale before the ttl itself', () => {
+    // A misconfigured STALE_MAX_AGE below CACHE_TTL must not shorten the fresh
+    // window.
+    cache.set('k', { v: 1 }, 10_000, 1000);
+    vi.advanceTimersByTime(9000);
+    expect(cache.get<{ v: number }>('k')).toEqual({ v: 1 });
+  });
+
+  it('evicts the oldest entry when capacity is exceeded', () => {
+    for (let i = 0; i < 201; i++) cache.set(`k${i}`, i, 60_000);
+    expect(cache.get('k0')).toBeNull();
+    expect(cache.get('k200')).toBe(200);
+  });
+
+  it('delete() removes the entry from get() and getStale()', () => {
+    cache.set('k', { v: 1 }, 1000, 60_000);
+    cache.delete('k');
+    expect(cache.get('k')).toBeNull();
+    expect(cache.getStale('k')).toBeNull();
+  });
+});
+```
+
+- [ ] **Step 2: Test laufen lassen und Fehlschlag prüfen**
+
+Run: `npm run test:unit -- lib/__tests__/cache-stale.test.ts`
+Erwartung: FAIL — `cache.getStale is not a function`.
+
+- [ ] **Step 3: `lib/cache.ts` implementieren**
+
+Vollständig ersetzen:
+
+```ts
+/**
+ * Simple in-memory LRU cache for Immich API responses.
+ * Avoids hammering the Immich server with identical requests.
+ *
+ * Entries carry two deadlines. `staleAt` is the normal TTL — past it, get()
+ * reports a miss and callers refetch. `hardExpiresAt` is the point past which
+ * the data is too old to show at all. Between the two, the entry survives as a
+ * fallback that getStale() hands out when Immich is unreachable, so a
+ * restarting server does not turn the gallery into an error page.
+ */
+
+interface CacheEntry<T> {
+  data: T;
+  staleAt: number;
+  hardExpiresAt: number;
+}
+
+const DEFAULT_STALE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+class MemoryCache {
+  private store = new Map<string, CacheEntry<unknown>>();
+  private maxEntries = 200;
+
+  get size(): number {
+    return this.store.size;
+  }
+
+  /** Move an entry to the newest end of the LRU order. */
+  private touch(key: string, entry: CacheEntry<unknown>): void {
+    this.store.delete(key);
+    this.store.set(key, entry);
+  }
+
+  /** Fresh data only. Returns null once the TTL has elapsed. */
+  get<T>(key: string): T | null {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+
+    const now = Date.now();
+
+    if (now > entry.hardExpiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+
+    // Past the TTL the entry is no longer fresh, but it is deliberately kept
+    // so getStale() can still use it.
+    if (now > entry.staleAt) return null;
+
+    this.touch(key, entry);
+    return entry.data as T;
+  }
+
+  /**
+   * Fresh *or* stale data. Only for the upstream-unreachable path — prefer
+   * get() everywhere else.
+   */
+  getStale<T>(key: string): T | null {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+
+    if (Date.now() > entry.hardExpiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+
+    this.touch(key, entry);
+    return entry.data as T;
+  }
+
+  set<T>(key: string, data: T, ttlMs: number, staleMaxAgeMs = DEFAULT_STALE_MAX_AGE_MS): void {
+    if (this.store.has(key)) {
+      this.store.delete(key);
+    } else if (this.store.size >= this.maxEntries) {
+      const firstKey = this.store.keys().next().value;
+      if (firstKey) this.store.delete(firstKey);
+    }
+
+    const now = Date.now();
+    this.store.set(key, {
+      data,
+      staleAt: now + ttlMs,
+      // Measured from write time, and never shorter than the TTL itself.
+      hardExpiresAt: now + Math.max(ttlMs, staleMaxAgeMs),
+    });
+  }
+
+  delete(key: string): void {
+    this.store.delete(key);
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+}
+
+export const cache = new MemoryCache();
+export { DEFAULT_STALE_MAX_AGE_MS };
+```
+
+- [ ] **Step 4: Cache-Tests prüfen**
+
+Run: `npm run test:unit -- lib/__tests__/cache-stale.test.ts`
+Erwartung: 8 Tests PASS.
+
+Run: `npm run test:unit`
+Erwartung: alle 218 Tests grün. Schlägt `config-cache.test.ts` oder `immich.test.ts` fehl, weil ein Test auf das Löschen beim Ablauf gebaut hat, den Test auf `getStale()` umstellen — nicht die Implementierung.
+
+- [ ] **Step 5: `STALE_MAX_AGE` durch Env und Config reichen**
+
+In `lib/env.ts` im `Env`-Interface direkt nach `CACHE_TTL: number;` ergänzen:
+
+```ts
+  STALE_MAX_AGE: number;
+```
+
+In `parseEnv()` nach dem `cacheTtl`-Block einfügen:
+
+```ts
+  // How long an expired cache entry may still be served while Immich is
+  // unreachable. 0 disables the fallback.
+  const staleMaxAgeStr = process.env.STALE_MAX_AGE;
+  const staleMaxAge =
+    staleMaxAgeStr && !isNaN(parseInt(staleMaxAgeStr, 10))
+      ? parseInt(staleMaxAgeStr, 10)
+      : 86400; // 24 hours
+```
+
+Im Rückgabeobjekt nach `CACHE_TTL: Math.max(0, cacheTtl),` einfügen:
+
+```ts
+    STALE_MAX_AGE: Math.max(0, staleMaxAge),
+```
+
+In `lib/config/schema.ts` im `AppConfig`-Interface neben `cacheTtl` ergänzen:
+
+```ts
+  staleMaxAge: number;
+```
+
+In `lib/config/index.ts` **beide** Rückgabepfade ergänzen — jeweils direkt nach `cacheTtl: env.CACHE_TTL * 1000,` (Zeilen 278 und 358):
+
+```ts
+    staleMaxAge: env.STALE_MAX_AGE * 1000,
+```
+
+In `.env.local.example` unterhalb des `CACHE_TTL`-Eintrags:
+
+```sh
+# How long (in seconds) an expired cache entry may still be served while the
+# Immich server is unreachable. Keeps the public gallery online across an
+# Immich restart instead of showing an error page. Set to 0 to disable.
+# Default: 86400 (24 hours)
+STALE_MAX_AGE=86400
+```
+
+- [ ] **Step 6: Typecheck**
+
+Run: `npx tsc --noEmit`
+Erwartung: 0 Fehler. Meldet `config-safe.test.ts` oder `config.test.ts` das neue Pflichtfeld, dort `staleMaxAge` in den gemockten Env- bzw. Erwartungsobjekten ergänzen.
+
+- [ ] **Step 7: Immich-Test für den Stale-Fallback schreiben**
+
+An `lib/__tests__/immich.test.ts` anhängen. Zuvor im dortigen `vi.mock('../config', …)`-Block bei den anderen Feldern ergänzen:
+
+```ts
+      staleMaxAge: 86_400_000,
+```
+
+Dann ans Dateiende:
+
+```ts
+describe('stale fallback when Immich is unavailable', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    cache.clear();
+  });
+
+  it('serves the previously cached album list instead of throwing', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      headers: { get: () => 'application/json' },
+      json: async () => [
+        {
+          id: 'album-1',
+          albumName: 'Original',
+          description: '',
+          albumThumbnailAssetId: null,
+          assetCount: 1,
+          assets: [],
+          createdAt: '',
+          updatedAt: '',
+          order: 'desc',
+        },
+      ],
+    });
+
+    const fresh = await immich.getAlbums();
+    expect(fresh).toHaveLength(1);
+
+    vi.useFakeTimers();
+    vi.advanceTimersByTime(60_000);
+    mockFetch.mockRejectedValue(new Error('ECONNREFUSED'));
+
+    const stale = await immich.getAlbums();
+    vi.useRealTimers();
+
+    expect(stale).toHaveLength(1);
+    expect(stale[0].id).toBe('album-1');
+  });
+
+  it('still throws when there is nothing cached to fall back to', async () => {
+    mockFetch.mockRejectedValue(new Error('ECONNREFUSED'));
+    await expect(immich.getAlbums()).rejects.toThrow(ImmichUnavailableError);
+  });
+
+  it('does not swallow a definitive 404 as an outage', async () => {
+    // A missing album must keep reporting missing, not fall back to stale data.
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 404,
+      statusText: 'Not Found',
+      headers: { get: () => 'application/json' },
+    });
+    await expect(immich.getAlbum('album-1')).resolves.toBeNull();
+  });
+
+  it('still refuses albums outside the allowlist', async () => {
+    mockFetch.mockRejectedValue(new Error('ECONNREFUSED'));
+    await expect(immich.getAlbum('not-allowed')).resolves.toBeNull();
+  });
+});
+```
+
+Der Import am Dateikopf muss `ImmichUnavailableError` mitführen:
+
+```ts
+import { immich, ImmichUnavailableError } from '../immich';
+```
+
+- [ ] **Step 8: Test laufen lassen und Fehlschlag prüfen**
+
+Run: `npm run test:unit -- lib/__tests__/immich.test.ts`
+Erwartung: Der erste neue Test schlägt fehl — `getAlbums()` wirft, statt die gecachte Liste zu liefern.
+
+- [ ] **Step 9: Stale-Fallback in `lib/immich.ts` einbauen**
+
+Direkt nach dem `private get config()`-Getter einen Helfer einfügen:
+
+```ts
+  /** Cache write that carries the configured stale window. */
+  private cacheSet<T>(key: string, data: T): void {
+    cache.set(key, data, this.config.cacheTtl, this.config.staleMaxAge);
+  }
+
+  /**
+   * Last resort when Immich is unavailable: hand back the most recent known
+   * good answer rather than failing the page. Only successes ever reach the
+   * cache, so this cannot resurrect an outage — and past staleMaxAge the entry
+   * is gone and the error propagates as before.
+   */
+  private staleOrThrow<T>(cacheKey: string, error: unknown, label: string): T {
+    if (error instanceof ImmichUnavailableError) {
+      const stale = cache.getStale<T>(cacheKey);
+      if (stale !== null) {
+        console.warn(`[Immich] ⚠️ Upstream unavailable — serving stale ${label}`);
+        return stale;
+      }
+    }
+    throw error;
+  }
+```
+
+All drei Methoden haben heute die Form `try { … } finally { … }` ohne `catch` — ein geworfener `ImmichUnavailableError` läuft ungefangen durch das `finally` und propagiert. Vor jedes bestehende `finally` wird ein `catch` eingefügt.
+
+In `getAlbums()` den Block
+
+```ts
+      } finally {
+        this.pendingAlbumsPromise = null;
+      }
+```
+
+ersetzen durch:
+
+```ts
+      } catch (error) {
+        return this.staleOrThrow<ImmichAlbum[]>(cacheKey, error, 'album list');
+      } finally {
+        this.pendingAlbumsPromise = null;
+      }
+```
+
+In `getAlbum()` den Block
+
+```ts
+      } finally {
+        this.pendingAlbumPromises.delete(albumId);
+      }
+```
+
+ersetzen durch:
+
+```ts
+      } catch (error) {
+        return this.staleOrThrow<ImmichAlbum>(cacheKey, error, `album ${albumId}`);
+      } finally {
+        this.pendingAlbumPromises.delete(albumId);
+      }
+```
+
+In `getAssetInfo()` den Block
+
+```ts
+      } finally {
+        this.pendingAssetPromises.delete(assetId);
+      }
+```
+
+ersetzen durch:
+
+```ts
+      } catch (error) {
+        return this.staleOrThrow<ImmichAsset>(cacheKey, error, `asset ${assetId}`);
+      } finally {
+        this.pendingAssetPromises.delete(assetId);
+      }
+```
+
+`lib/immich.ts` enthält fünf `cache.set(cacheKey, …, this.config.cacheTtl)`-Aufrufe. Nur die drei mit einem echten Ergebnis umstellen:
+
+- `cache.set(cacheKey, filtered, this.config.cacheTtl);` in `getAlbums()` → `this.cacheSet(cacheKey, filtered);`
+- `cache.set(cacheKey, album, this.config.cacheTtl);` in `getAlbum()` → `this.cacheSet(cacheKey, album);`
+- `cache.set(cacheKey, asset, this.config.cacheTtl);` in `getAssetInfo()` → `this.cacheSet(cacheKey, asset);`
+
+**Nicht umstellen:** die beiden `cache.set(cacheKey, MISSING, this.config.cacheTtl);`-Aufrufe (in `getAlbum()` und `getAssetInfo()`, direkt nach `if (!album) {`/`if (!asset) {`). Ein „existiert nicht" soll nach der normalen TTL neu geprüft werden und nicht 24 Stunden festhängen — genau das war die Begründung in #394.
+
+- [ ] **Step 10: Tests prüfen**
+
+Run: `npm run test:unit -- lib/__tests__/immich.test.ts`
+Erwartung: alle Tests PASS, inklusive der vier neuen.
+
+Der dritte neue Test ist der wichtige: Ein definitives 404 darf **nicht** in den Stale-Pfad laufen. `staleOrThrow` prüft deshalb auf `instanceof ImmichUnavailableError` — ein 404 erzeugt gar keinen Fehler, sondern `null`, und erreicht das `catch` nie.
+
+- [ ] **Step 11: Gesamtprüfung**
+
+Run: `npm run test:unit`
+Erwartung: 222 Tests grün.
+
+Run: `npx tsc --noEmit`
+Erwartung: 0 Fehler.
+
+Run: `npm run lint`
+Erwartung: 0 Fehler.
+
+Run: `npm run build`
+Erwartung: Build erfolgreich.
+
+- [ ] **Step 12: Commit**
+
+```bash
+npx prettier --write lib/cache.ts lib/immich.ts lib/env.ts lib/config/schema.ts lib/config/index.ts lib/__tests__/cache-stale.test.ts lib/__tests__/immich.test.ts .env.local.example
+git add lib/cache.ts lib/immich.ts lib/env.ts lib/config/schema.ts lib/config/index.ts lib/__tests__/cache-stale.test.ts lib/__tests__/immich.test.ts .env.local.example
+git commit -m "feat: serve stale cache entries while Immich is unavailable"
+```
+
+---
+
+## Task 3: Lade-Skeletons
+
+**Warum:** Alle Galerieseiten sind `force-dynamic` und warten vollständig auf Immich. Mit `IMMICH_TIMEOUT_MS` (Default 15 s) kann diese Wartezeit im Störungsfall lang werden — ohne `loading.tsx` sieht der Besucher währenddessen nichts.
+
+**Files:**
+- Create: `app/loading.module.css`
+- Create: `app/loading.tsx`
+- Create: `app/[...path]/loading.tsx`
+
+**Interfaces:**
+- Consumes: Tokens aus `app/tokens.css`; die Grid-Variablen, die `app/[...path]/page.tsx` setzt.
+- Produces: nichts.
+
+- [ ] **Step 1: `app/loading.module.css` anlegen**
+
+```css
+/* Skeleton placeholders shown while a dynamic page waits on Immich. */
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(var(--grid-columns, 3), 1fr);
+  gap: var(--grid-gap, 12px);
+}
+
+.tile {
+  aspect-ratio: var(--grid-aspect-ratio, 1);
+  border-radius: var(--radius-sm);
+  background: var(--bg-secondary);
+  animation: skeleton-pulse 1.6s ease-in-out infinite;
+}
+
+.heading {
+  height: 2.5rem;
+  width: min(320px, 60%);
+  border-radius: var(--radius-sm);
+  background: var(--bg-secondary);
+  margin-bottom: 24px;
+  animation: skeleton-pulse 1.6s ease-in-out infinite;
+}
+
+@keyframes skeleton-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+
+  50% {
+    opacity: 0.45;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .tile,
+  .heading {
+    animation: none;
+  }
+}
+
+@media (max-width: 640px) {
+  .grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+```
+
+- [ ] **Step 2: `app/[...path]/loading.tsx` anlegen**
+
+```tsx
+/**
+ * Instant shell for album and subpage routes. These are force-dynamic and wait
+ * on a live Immich round-trip — up to IMMICH_TIMEOUT_MS when the server is
+ * struggling — so without this the viewer stares at a blank page.
+ */
+
+import styles from '../loading.module.css';
+
+export default function Loading() {
+  return (
+    <>
+      <div className={styles.heading} aria-hidden="true" />
+      <div className={styles.grid} role="status" aria-label="Loading photos">
+        {Array.from({ length: 9 }).map((_, i) => (
+          <div key={i} className={styles.tile} />
+        ))}
+      </div>
+    </>
+  );
+}
+```
+
+- [ ] **Step 3: `app/loading.tsx` anlegen**
+
+```tsx
+/**
+ * Instant shell for the homepage.
+ */
+
+import styles from './loading.module.css';
+
+export default function Loading() {
+  return (
+    <div className={styles.grid} role="status" aria-label="Loading gallery">
+      {Array.from({ length: 6 }).map((_, i) => (
+        <div key={i} className={styles.tile} />
+      ))}
+    </div>
+  );
+}
+```
+
+- [ ] **Step 4: Im Browser prüfen**
+
+Run: `npm run dev`
+
+In den DevTools unter „Network" auf „Slow 3G" drosseln, dann eine Album-Seite laden.
+Erwartung: Kachel-Skeletons erscheinen sofort und werden von den echten Fotos abgelöst. Kein Layoutsprung, keine leere weiße Seite.
+
+- [ ] **Step 5: Verifizieren**
+
+Run: `npx tsc --noEmit`
+Erwartung: 0 Fehler.
+
+Run: `npm run lint`
+Erwartung: 0 Fehler.
+
+Run: `npm run build`
+Erwartung: Build erfolgreich.
+
+- [ ] **Step 6: Commit**
+
+```bash
+npx prettier --write app/loading.tsx "app/[...path]/loading.tsx" app/loading.module.css
+git add app/loading.tsx "app/[...path]/loading.tsx" app/loading.module.css
+git commit -m "feat: add loading skeletons for dynamic gallery routes"
+```
+
+---
+
+## Task 4: Dokumentation
+
+**Files:**
+- Modify: `README.md`
+- Modify: `CLAUDE.md`
+
+- [ ] **Step 1: `README.md` ergänzen**
+
+Bei den Umgebungsvariablen, neben `CACHE_TTL` und `IMMICH_TIMEOUT_MS`:
+
+```md
+| `STALE_MAX_AGE` | `86400` | Seconds an expired cache entry may still be served while Immich is unreachable. Keeps the public gallery online across an Immich restart. Set to `0` to disable. |
+```
+
+Und einen Abschnitt:
+
+```md
+### Behaviour when Immich is unreachable
+
+Folio buffers your gallery rather than merely proxying it:
+
+- Album pages keep serving the last known good data for up to `STALE_MAX_AGE`.
+- Once nothing cached is left, they return `503`, never `404` — a `404` would
+  tell search engines to drop a URL that still exists.
+- Outages are never cached, so the gallery recovers as soon as Immich does.
+
+The cache lives in the process, so it is empty after a container restart.
+```
+
+Zusätzlich im Sicherheitsabschnitt:
+
+```md
+### Un-publishing an album does not revoke image links
+
+Asset tokens are deterministic — the same photo always yields the same token,
+which is what lets browsers cache images. The image proxy validates the token
+but does not re-check album membership per request.
+
+Removing an album from `gallery.yaml` hides it from the site, but image URLs
+already handed out keep working. To invalidate them, rotate `AUTH_SECRET` —
+this also signs out every password-protected gallery and admin session.
+```
+
+- [ ] **Step 2: `CLAUDE.md` aktualisieren**
+
+Den Absatz zur In-Memory-LRU im Abschnitt „Immich client" ersetzen:
+
+```md
+- **In-memory LRU cache** (`lib/cache.ts`) — 200-entry LRU. Entries carry two deadlines: `staleAt` (the `CACHE_TTL` window, after which `get()` reports a miss) and `hardExpiresAt` (`STALE_MAX_AGE`, after which the entry is dropped). Between the two, `getStale()` still returns the data — `lib/immich.ts` uses this to keep serving the last known albums when a request fails with `ImmichUnavailableError`. Definitive 404s are cached as a `MISSING` sentinel under the normal TTL and are deliberately excluded from the stale window. Cache keys: `albums-list`, `album-<id>`, `asset-<id>`.
+```
+
+Im Abschnitt „Code conventions" ergänzen:
+
+```md
+- **Route handlers are testable** — `vitest.config.ts` includes `app/**/__tests__/**/*.test.ts`. Logic that lives in a route (guards, header sanitisation) belongs in a route-level test; do not extract it into `lib/` purely to make it reachable by the test runner.
+```
+
+- [ ] **Step 3: Verifizieren**
+
+Run: `npm run format:check`
+Erwartung: keine Beanstandungen. Andernfalls `npx prettier --write README.md CLAUDE.md`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md CLAUDE.md
+git commit -m "docs: document stale cache window and route-test convention"
+```
+
+---
+
+## Verifikation von Ende zu Ende
+
+**1. Testsuite** — `npm run test:unit`: 222 Tests grün (Baseline 210 + 33 neue − 21 … die exakte Summe ergibt sich aus den Task-Schritten; entscheidend ist, dass keine bestehende Datei rot wird).
+
+**2. Regressionsbremse Admin** — in einer Admin-Route die Guards auskommentieren, `npm run test:unit`: die Guard-Tests schlagen fehl. Zurücknehmen.
+
+**3. Regressionsbremse XSS** — die Content-Type-Normalisierung in `app/api/image/[id]/route.ts` entfernen: die SVG/XML-Fälle schlagen fehl. Zurücknehmen.
+
+**4. Stale-Fallback live** — `npm run dev`, Album-Seite laden (füllt den Cache), dann den Immich-Container stoppen und neu laden.
+Erwartung: die Fotos sind weiterhin da; im Log steht `⚠️ Upstream unavailable — serving stale album`.
+
+**5. Kein Cache, kein Immich** — Dev-Server bei gestopptem Immich neu starten, Album-URL aufrufen:
+
+```bash
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/<album-slug>
+```
+
+Erwartung: `500` oder `503` — **kein** `404`.
+
+**6. Erholung** — Immich wieder starten, Seite neu laden.
+Erwartung: frische Daten, keine eingebrannte Fehlermeldung.
+
+**7. Skeletons** — mit „Slow 3G" eine Album-Seite laden.
+Erwartung: sofort Kacheln, kein weißer Bildschirm.
diff --git a/lib/__tests__/cache-stale.test.ts b/lib/__tests__/cache-stale.test.ts
new file mode 100644
index 0000000..71c416c
--- /dev/null
+++ b/lib/__tests__/cache-stale.test.ts
@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { cache } from '../cache';
+
+describe('MemoryCache stale window', () => {
+  beforeEach(() => {
+    cache.clear();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('returns fresh entries from get()', () => {
+    cache.set('k', { v: 1 }, 1000);
+    expect(cache.get<{ v: number }>('k')).toEqual({ v: 1 });
+  });
+
+  it('returns null from get() once the ttl elapsed', () => {
+    cache.set('k', { v: 1 }, 1000);
+    vi.advanceTimersByTime(1001);
+    expect(cache.get('k')).toBeNull();
+  });
+
+  it('still returns the value from getStale() after the ttl elapsed', () => {
+    cache.set('k', { v: 1 }, 1000, 60_000);
+    vi.advanceTimersByTime(1001);
+    expect(cache.getStale<{ v: number }>('k')).toEqual({ v: 1 });
+  });
+
+  it('drops the entry from getStale() past the hard max age', () => {
+    cache.set('k', { v: 1 }, 1000, 5000);
+    vi.advanceTimersByTime(5001);
+    expect(cache.getStale('k')).toBeNull();
+  });
+
+  it('does not let get() destroy the stale fallback', () => {
+    // get() must not delete an expired entry — otherwise the fallback is gone
+    // the moment any caller asks for fresh data first.
+    cache.set('k', { v: 1 }, 1000, 60_000);
+    vi.advanceTimersByTime(1001);
+    expect(cache.get('k')).toBeNull();
+    expect(cache.getStale<{ v: number }>('k')).toEqual({ v: 1 });
+  });
+
+  it('never expires stale before the ttl itself', () => {
+    // A misconfigured STALE_MAX_AGE below CACHE_TTL must not shorten the fresh
+    // window.
+    cache.set('k', { v: 1 }, 10_000, 1000);
+    vi.advanceTimersByTime(9000);
+    expect(cache.get<{ v: number }>('k')).toEqual({ v: 1 });
+  });
+
+  it('evicts the oldest entry when capacity is exceeded', () => {
+    for (let i = 0; i < 201; i++) cache.set(`k${i}`, i, 60_000);
+    expect(cache.get('k0')).toBeNull();
+    expect(cache.get('k200')).toBe(200);
+  });
+
+  it('delete() removes the entry from get() and getStale()', () => {
+    cache.set('k', { v: 1 }, 1000, 60_000);
+    cache.delete('k');
+    expect(cache.get('k')).toBeNull();
+    expect(cache.getStale('k')).toBeNull();
+  });
+});
diff --git a/lib/__tests__/immich.test.ts b/lib/__tests__/immich.test.ts
index 4db7466..97809ed 100644
--- a/lib/__tests__/immich.test.ts
+++ b/lib/__tests__/immich.test.ts
@@ -20,6 +20,7 @@ vi.mock('../config', async () => {
       // written, which would make any caching assertion flaky. Isolation comes
       // from the cache.clear() in beforeEach, not from an unusable TTL.
       cacheTtl: 60_000,
+      staleMaxAge: 86_400_000,
       immichTimeoutMs: 15000,
     }),
   };
@@ -496,3 +497,68 @@ describe('ImmichClient', () => {
     });
   });
 });
+
+describe('stale fallback when Immich is unavailable', () => {
+  const mockFetch = global.fetch as any;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    cache.clear();
+  });
+
+  it('serves the previously cached album list instead of throwing', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      headers: { get: () => 'application/json' },
+      json: async () => [
+        {
+          id: 'album-1',
+          albumName: 'Original',
+          description: '',
+          albumThumbnailAssetId: null,
+          assetCount: 1,
+          assets: [],
+          createdAt: '',
+          updatedAt: '',
+          order: 'desc',
+        },
+      ],
+    });
+
+    const fresh = await immich.getAlbums();
+    expect(fresh).toHaveLength(1);
+
+    vi.useFakeTimers();
+    // Strictly past cacheTtl (60_000ms) so cache.get()'s fresh-only check
+    // misses and the fallback path — not a lucky cache hit — is what's tested.
+    vi.advanceTimersByTime(60_001);
+    mockFetch.mockRejectedValue(new Error('ECONNREFUSED'));
+
+    const stale = await immich.getAlbums();
+    vi.useRealTimers();
+
+    expect(stale).toHaveLength(1);
+    expect(stale[0].id).toBe('album-1');
+  });
+
+  it('still throws when there is nothing cached to fall back to', async () => {
+    mockFetch.mockRejectedValue(new Error('ECONNREFUSED'));
+    await expect(immich.getAlbums()).rejects.toThrow(ImmichUnavailableError);
+  });
+
+  it('does not swallow a definitive 404 as an outage', async () => {
+    // A missing album must keep reporting missing, not fall back to stale data.
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 404,
+      statusText: 'Not Found',
+      headers: { get: () => 'application/json' },
+    });
+    await expect(immich.getAlbum('album-1')).resolves.toBeNull();
+  });
+
+  it('still refuses albums outside the allowlist', async () => {
+    mockFetch.mockRejectedValue(new Error('ECONNREFUSED'));
+    await expect(immich.getAlbum('not-allowed')).resolves.toBeNull();
+  });
+});
diff --git a/lib/cache.ts b/lib/cache.ts
index 85a5a77..e6c0770 100644
--- a/lib/cache.ts
+++ b/lib/cache.ts
@@ -1,13 +1,22 @@
 /**
  * Simple in-memory LRU cache for Immich API responses.
  * Avoids hammering the Immich server with identical requests.
+ *
+ * Entries carry two deadlines. `staleAt` is the normal TTL — past it, get()
+ * reports a miss and callers refetch. `hardExpiresAt` is the point past which
+ * the data is too old to show at all. Between the two, the entry survives as a
+ * fallback that getStale() hands out when Immich is unreachable, so a
+ * restarting server does not turn the gallery into an error page.
  */
 
 interface CacheEntry<T> {
   data: T;
-  expiresAt: number;
+  staleAt: number;
+  hardExpiresAt: number;
 }
 
+const DEFAULT_STALE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+
 class MemoryCache {
   private store = new Map<string, CacheEntry<unknown>>();
   private maxEntries = 200;
@@ -16,35 +25,63 @@ class MemoryCache {
     return this.store.size;
   }
 
+  /** Move an entry to the newest end of the LRU order. */
+  private touch(key: string, entry: CacheEntry<unknown>): void {
+    this.store.delete(key);
+    this.store.set(key, entry);
+  }
+
+  /** Fresh data only. Returns null once the TTL has elapsed. */
   get<T>(key: string): T | null {
     const entry = this.store.get(key);
     if (!entry) return null;
 
-    if (Date.now() > entry.expiresAt) {
+    const now = Date.now();
+
+    if (now > entry.hardExpiresAt) {
       this.store.delete(key);
       return null;
     }
 
-    // LRU: Move accessed item to the back of the Map (newest)
-    this.store.delete(key);
-    this.store.set(key, entry);
+    // Past the TTL the entry is no longer fresh, but it is deliberately kept
+    // so getStale() can still use it.
+    if (now > entry.staleAt) return null;
 
+    this.touch(key, entry);
     return entry.data as T;
   }
 
-  set<T>(key: string, data: T, ttlMs: number): void {
-    // If key exists, delete it first to ensure we push it to the back
+  /**
+   * Fresh *or* stale data. Only for the upstream-unreachable path — prefer
+   * get() everywhere else.
+   */
+  getStale<T>(key: string): T | null {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+
+    if (Date.now() > entry.hardExpiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+
+    this.touch(key, entry);
+    return entry.data as T;
+  }
+
+  set<T>(key: string, data: T, ttlMs: number, staleMaxAgeMs = DEFAULT_STALE_MAX_AGE_MS): void {
     if (this.store.has(key)) {
       this.store.delete(key);
     } else if (this.store.size >= this.maxEntries) {
-      // Evict oldest entry (first item) if at capacity
       const firstKey = this.store.keys().next().value;
       if (firstKey) this.store.delete(firstKey);
     }
 
+    const now = Date.now();
     this.store.set(key, {
       data,
-      expiresAt: Date.now() + ttlMs,
+      staleAt: now + ttlMs,
+      // Measured from write time, and never shorter than the TTL itself.
+      hardExpiresAt: now + Math.max(ttlMs, staleMaxAgeMs),
     });
   }
 
@@ -58,3 +95,4 @@ class MemoryCache {
 }
 
 export const cache = new MemoryCache();
+export { DEFAULT_STALE_MAX_AGE_MS };
diff --git a/lib/config/index.ts b/lib/config/index.ts
index 0ba193e..1ea87f6 100644
--- a/lib/config/index.ts
+++ b/lib/config/index.ts
@@ -276,6 +276,7 @@ export function getConfig(): AppConfig {
       albumPasswords: {},
       albumHeroImages: {},
       cacheTtl: env.CACHE_TTL * 1000,
+      staleMaxAge: env.STALE_MAX_AGE * 1000,
       immichTimeoutMs: env.IMMICH_TIMEOUT_MS,
       rateLimitRpm: env.RATE_LIMIT_RPM,
       trustedProxyHops: env.TRUSTED_PROXY_HOPS,
@@ -356,6 +357,7 @@ export function getConfig(): AppConfig {
     albumPasswords,
     albumHeroImages,
     cacheTtl: env.CACHE_TTL * 1000,
+    staleMaxAge: env.STALE_MAX_AGE * 1000,
     immichTimeoutMs: env.IMMICH_TIMEOUT_MS,
     rateLimitRpm: env.RATE_LIMIT_RPM,
     trustedProxyHops: env.TRUSTED_PROXY_HOPS,
diff --git a/lib/config/schema.ts b/lib/config/schema.ts
index 9f55dbb..d25e3f2 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;
+  /** How long (ms) an expired cache entry may still be served while Immich is unreachable. */
+  staleMaxAge: number;
   /** Response-wait budget for Immich API calls. Does not cap image/video body transfer. */
   immichTimeoutMs: number;
   rateLimitRpm: number;
diff --git a/lib/env.ts b/lib/env.ts
index 86a38e6..8eef055 100644
--- a/lib/env.ts
+++ b/lib/env.ts
@@ -9,6 +9,7 @@ export interface Env {
   SITE_TITLE: string;
   SITE_SUBTITLE: string;
   CACHE_TTL: number;
+  STALE_MAX_AGE: number;
   IMAGE_CACHE_VERSION: string;
   IMMICH_TIMEOUT_MS: number;
   RATE_LIMIT_RPM: number;
@@ -37,6 +38,13 @@ function parseEnv(): Env {
   const cacheTtl =
     cacheTtlStr && !isNaN(parseInt(cacheTtlStr, 10)) ? parseInt(cacheTtlStr, 10) : 300;
 
+  // How long an expired cache entry may still be served while Immich is
+  // unreachable. Keeps the public gallery online across an Immich restart
+  // instead of showing an error page. 0 disables the fallback.
+  const staleMaxAgeStr = process.env.STALE_MAX_AGE;
+  const staleMaxAge =
+    staleMaxAgeStr && !isNaN(parseInt(staleMaxAgeStr, 10)) ? parseInt(staleMaxAgeStr, 10) : 86400; // 24 hours
+
   // 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
@@ -91,6 +99,7 @@ function parseEnv(): Env {
     SITE_TITLE: process.env.SITE_TITLE || 'Gallery',
     SITE_SUBTITLE: process.env.SITE_SUBTITLE || '',
     CACHE_TTL: Math.max(0, cacheTtl),
+    STALE_MAX_AGE: Math.max(0, staleMaxAge),
     // 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".
diff --git a/lib/immich.ts b/lib/immich.ts
index 2d7efc3..e94164b 100644
--- a/lib/immich.ts
+++ b/lib/immich.ts
@@ -127,6 +127,28 @@ class ImmichClient {
     return getConfig();
   }
 
+  /** Cache write that carries the configured stale window. */
+  private cacheSet<T>(key: string, data: T): void {
+    cache.set(key, data, this.config.cacheTtl, this.config.staleMaxAge);
+  }
+
+  /**
+   * Last resort when Immich is unavailable: hand back the most recent known
+   * good answer rather than failing the page. Only successes ever reach the
+   * cache, so this cannot resurrect an outage — and past staleMaxAge the entry
+   * is gone and the error propagates as before.
+   */
+  private staleOrThrow<T>(cacheKey: string, error: unknown, label: string): T {
+    if (error instanceof ImmichUnavailableError) {
+      const stale = cache.getStale<T>(cacheKey);
+      if (stale !== null) {
+        console.warn(`[Immich] ⚠️ Upstream unavailable — serving stale ${label}`);
+        return stale;
+      }
+    }
+    throw error;
+  }
+
   private async request<T>(endpoint: string, body?: unknown): Promise<T | null> {
     if (this.config.needsSetup) return null;
 
@@ -402,8 +424,10 @@ class ImmichClient {
           console.log('─'.repeat(80) + '\n');
         }
 
-        cache.set(cacheKey, filtered, this.config.cacheTtl);
+        this.cacheSet(cacheKey, filtered);
         return filtered;
+      } catch (error) {
+        return this.staleOrThrow<ImmichAlbum[]>(cacheKey, error, 'album list');
       } finally {
         this.pendingAlbumsPromise = null;
       }
@@ -565,8 +589,10 @@ class ImmichClient {
         album.description = description;
         album.slug = slugify(name);
 
-        cache.set(cacheKey, album, this.config.cacheTtl);
+        this.cacheSet(cacheKey, album);
         return album;
+      } catch (error) {
+        return this.staleOrThrow<ImmichAlbum>(cacheKey, error, `album ${albumId}`);
       } finally {
         this.pendingAlbumPromises.delete(albumId);
       }
@@ -629,8 +655,10 @@ class ImmichClient {
           return null;
         }
 
-        cache.set(cacheKey, asset, this.config.cacheTtl);
+        this.cacheSet(cacheKey, asset);
         return asset;
+      } catch (error) {
+        return this.staleOrThrow<ImmichAsset>(cacheKey, error, `asset ${assetId}`);
       } finally {
         this.pendingAssetPromises.delete(assetId);
       }
diff --git a/vitest.config.ts b/vitest.config.ts
index 1b8e2c3..930919d 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -5,7 +5,7 @@ export default defineConfig({
   test: {
     environment: 'node',
     setupFiles: ['./vitest.setup.ts'],
-    include: ['lib/__tests__/**/*.test.ts'],
+    include: ['lib/__tests__/**/*.test.ts', 'app/**/__tests__/**/*.test.ts'],
     coverage: {
       provider: 'v8',
       include: ['lib/**/*.ts'],