From 716ae14b0f682decbe0516077ace50231a6a1075 Mon Sep 17 00:00:00 2001
From: Ralksta <16941050+ralksta@users.noreply.github.com>
Date: Fri, 7 Aug 2026 11:07:34 +0200
Subject: [PATCH] Close the gaps left after v0.9.2's outage handling: route
 tests, stale cache, loading states (#397)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs: brainstorm resilience/adoption features and plan follow-up work

Brainstorm and deep-dive on where Immich Folio breaks under Immich
outages and what blocks self-hosted adoption, plus an implementation
plan for the remaining gaps after v0.9.2 (route-handler tests,
stale-while-error caching, loading skeletons).

* test: enable route-handler tests and cover admin guards and image content-type

vitest.config.ts only ran lib/__tests__/**, so route handlers were
structurally untestable. Two mechanisms live only at the route level and
cannot be extracted the way lib/imageSize.ts was: the admin auth guards
and the image proxy's Content-Type sanitisation (the stored-XSS fix from
c2fa8e7). Both were correct but unverified by any test.

Adds a table-driven test over all ten guarded /api/admin/* handlers,
including a filesystem walk that fails if a future route is added
without a row in the table. Adds a route-level test for
/api/image/[id] covering token validation, the six Content-Type
rewrite cases, ETag/304, and the 404 vs 503 (ImmichUnavailableError)
distinction.

Verified both catch real regressions by temporarily removing the admin
guards and the Content-Type rewrite and confirming the expected tests
fail, then restoring and confirming green again.

134 new tests (244 total, up from 210), tsc 0 errors, build succeeds.

* feat: serve stale cache entries while Immich is unavailable

v0.9.2 (#394) correctly split "gone" (404/410) from "unavailable"
(ImmichUnavailableError), and pages now render a 5xx instead of a false
404 during an outage — but that 5xx still replaced a gallery that had
loaded fine seconds earlier. lib/cache.ts deleted expired entries on
access, so nothing survived long enough to fall back to.

Cache entries now carry two deadlines: staleAt (the existing CACHE_TTL,
after which get() still reports a miss) and hardExpiresAt (the new
STALE_MAX_AGE, default 24h, after which the entry is dropped entirely).
Between the two, getStale() can still return the data.

getAlbums(), getAlbum() and getAssetInfo() catch ImmichUnavailableError
and fall back to getStale() before propagating. The two MISSING-sentinel
writes (definitive 404s) are deliberately left on the short cacheTtl
window — a corrected asset ID should take effect after the normal TTL,
not sit in the 24h stale window meant for outages.

STALE_MAX_AGE=0 disables the fallback. Verified the fallback only
engages on a real outage, not on a cache hit at the TTL boundary, and
that a definitive 404 still reports missing rather than falling back.

256 tests (up from 244), tsc 0 errors, build succeeds.

* feat: add loading skeletons for dynamic gallery routes

Every gallery route is force-dynamic and waits on a live Immich
round-trip — up to IMMICH_TIMEOUT_MS when the server is struggling —
with nothing rendered until it resolves. loading.tsx renders instantly
while the page component awaits its data.

Not browser-verified against live data: this worktree has no
.env.local and only .example content files, so the app boots into
setup mode (confirmed the dev server starts cleanly and the setup
screen renders, HTTP 200). tsc 0 errors, build succeeds, no new lint
errors.

* docs: document stale cache window, image token revocation, route-test convention

- README: STALE_MAX_AGE env var and a "Behaviour when Immich is
  unreachable" section (stale-serves-until-STALE_MAX_AGE, 503 not 404,
  outages never cached).
- docs/gallery-config.md: new "Image Token Revocation" subsection under
  System & Security — un-publishing an album does not revoke already
  issued image URLs; rotating AUTH_SECRET does.
- CLAUDE.md: updated cache description to cover the stale window and
  MISSING sentinel, and a new code-convention note that route-level
  logic (guards, header sanitisation) should get a route-level test
  rather than being extracted into lib/ just to reach the test runner.

---------

Co-authored-by: ralksta <ralksta@users.noreply.github.com>
---
 .env.local.example                            |    6 +
 CLAUDE.md                                     |   30 +-
 README.md                                     |   11 +
 app/[...path]/loading.tsx                     |   20 +
 app/api/admin/__tests__/admin-guards.test.ts  |  158 +++
 app/api/image/__tests__/image-route.test.ts   |  114 ++
 app/loading.module.css                        |   47 +
 app/loading.tsx                               |   15 +
 docs/brainstorm-2026-08-05.md                 |  336 +++++
 docs/deep-dive-2026-08-05.md                  |  364 ++++++
 docs/gallery-config.md                        |   20 +-
 .../plans/2026-08-05-resilience-boundaries.md | 1154 +++++++++++++++++
 lib/__tests__/cache-stale.test.ts             |   66 +
 lib/__tests__/immich.test.ts                  |   66 +
 lib/cache.ts                                  |   56 +-
 lib/config/index.ts                           |    2 +
 lib/config/schema.ts                          |    2 +
 lib/env.ts                                    |    9 +
 lib/immich.ts                                 |   34 +-
 vitest.config.ts                              |    2 +-
 20 files changed, 2478 insertions(+), 34 deletions(-)
 create mode 100644 app/[...path]/loading.tsx
 create mode 100644 app/api/admin/__tests__/admin-guards.test.ts
 create mode 100644 app/api/image/__tests__/image-route.test.ts
 create mode 100644 app/loading.module.css
 create mode 100644 app/loading.tsx
 create mode 100644 docs/brainstorm-2026-08-05.md
 create mode 100644 docs/deep-dive-2026-08-05.md
 create mode 100644 docs/superpowers/plans/2026-08-05-resilience-boundaries.md
 create mode 100644 lib/__tests__/cache-stale.test.ts

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'],