feat(documents): the vault surface

The page becomes one wide, calm filing-cabinet view: PageHeader with an
Upload action, a drop-target upload zone whose accept list and per-file
cap come from the usage endpoint (quota bar only above 80 %), a sticky
filter rail (200 ms debounced search focused by '/', nine type chips,
condition chips from linked episodes, a year segmenter, one-tap clear),
and the virtualized timeline below. Filter state lives in the URL so
every view is shareable and back-button-safe; uploads filtered to an
episode arrive pre-linked. Hovering a card prefetches detail metadata —
never the blob. Designed states: a skeleton grid that matches the loaded
layout, a teaching empty state, a distinct no-matches state, and a
retryable error card. /documents joins the shell's wide-container list;
the shell stays the single owner of the page frame. Locale bundles gain
the vault vocabulary in all six languages and drop the retired
extraction-review strings.

Plan-Task: W2-T1, W2-T4 (zone), W2-T5 (prefetch), W2-T6

src/app/documents/page.tsx

@@ -1,45 +1,18 @@
-"use client";
+import { Suspense } from "react";
 
-import { useEffect } from "react";
-import { useRouter } from "next/navigation";
-import { Loader2 } from "lucide-react";
-
-import { useAuth } from "@/hooks/use-auth";
-import { InboundDocumentsView } from "@/components/documents/inbound-documents-view";
+import { DocumentsView } from "@/components/documents/documents-view";
 
 /**
- * v1.25.0 (W-DOCS-IN) — inbound clinical documents entry.
- *
- * Born-gated on the resolved `modules.inboundDocuments` flag from
- * `GET /api/auth/me` (opt-in / default-off — the per-user opt-in AND the
- * operator server-wide kill-switch). An unauthenticated visitor is bounced to
- * login; an authenticated account without the module opted in is bounced home
- * (the nav entry is already hidden for them, so this only catches a direct URL
- * hit). Every `/api/documents/inbound/*` route also enforces the gate
- * server-side, so this is a UX redirect, not the security boundary.
+ * The Dokumente vault — server shell only. The client surface owns the
+ * module gate, the URL-backed filter state (which needs `useSearchParams`,
+ * hence the Suspense boundary), the virtualized timeline, and the upload
+ * queue. The route rides the AuthShell's wide-container flag: the shell
+ * owns the page frame, this file never re-implements paddings.
  */
 export default function DocumentsPage() {
-  const { user, isLoading, isAuthenticated } = useAuth();
-  const router = useRouter();
-
-  const enabled = user?.modules?.inboundDocuments === true;
-
-  useEffect(() => {
-    if (isLoading) return;
-    if (!isAuthenticated) {
-      router.push("/auth/login");
-    } else if (!enabled) {
-      router.push("/");
-    }
-  }, [isLoading, isAuthenticated, enabled, router]);
-
-  if (isLoading || !isAuthenticated || !enabled) {
-    return (
-      <div className="flex h-64 items-center justify-center">
-        <Loader2 className="text-primary h-8 w-8 animate-spin motion-reduce:animate-none" />
-      </div>
-    );
-  }
-
-  return <InboundDocumentsView />;
+  return (
+    <Suspense fallback={null}>
+      <DocumentsView />
+    </Suspense>
+  );
 }

src/components/documents/__tests__/documents-view-states.test.tsx

@@ -0,0 +1,97 @@
+import { describe, expect, it, vi } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+/**
+ * The vault page's designed states, pinned via single-pass static renders:
+ *
+ *   - first load paints the skeleton grid (`documents-loading`) — a shape
+ *     that matches the loaded card grid, never a bare spinner;
+ *   - an empty unfiltered corpus paints the TEACHING empty state (what
+ *     belongs here + an upload affordance), not the error copy;
+ *   - an empty FILTERED view paints the no-matches state with a
+ *     clear-filters affordance — a distinct state, per the standards a
+ *     failed query may never fall through to either.
+ */
+
+let mockSearch = "";
+const pushMock = vi.fn();
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({ push: pushMock, replace: vi.fn() }),
+  usePathname: () => "/documents",
+  useSearchParams: () => new URLSearchParams(mockSearch),
+}));
+
+vi.mock("@/hooks/use-auth", () => ({
+  useAuth: () => ({
+    user: { id: "u1", modules: { inboundDocuments: true } },
+    isLoading: false,
+    isAuthenticated: true,
+  }),
+}));
+
+vi.mock("@/lib/api/api-fetch", async () => {
+  const actual = await vi.importActual<typeof import("@/lib/api/api-fetch")>(
+    "@/lib/api/api-fetch",
+  );
+  return {
+    ...actual,
+    // Never resolves within the synchronous SSR render → queries whose
+    // cache is not seeded stay pending.
+    apiGet: () => new Promise(() => {}),
+    apiPatch: vi.fn(),
+    apiPost: vi.fn(),
+    apiDelete: vi.fn(),
+  };
+});
+
+import { I18nProvider } from "@/lib/i18n/context";
+import { queryKeys } from "@/lib/query-keys";
+import { DocumentsView } from "../documents-view";
+
+function render(search: string, seedList?: { kinds?: never } | object) {
+  mockSearch = search;
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  if (seedList !== undefined) {
+    queryClient.setQueryData(queryKeys.inboundDocumentList(seedList), {
+      pages: [{ documents: [], nextCursor: null }],
+      pageParams: [null],
+    });
+  }
+  return renderToStaticMarkup(
+    <QueryClientProvider client={queryClient}>
+      <I18nProvider initialLocale="en">
+        <DocumentsView />
+      </I18nProvider>
+    </QueryClientProvider>,
+  );
+}
+
+describe("<DocumentsView> states", () => {
+  it("first load: skeleton grid matching the card layout, no spinner", () => {
+    const html = render("");
+    expect(html).toContain('data-slot="documents-loading"');
+    expect(html).toContain('data-slot="skeleton"');
+    expect(html).toContain('data-slot="document-filter-bar"');
+    expect(html).toContain('data-slot="document-upload-zone"');
+    // A pending list must never read as an empty vault.
+    expect(html).not.toContain("Your document vault is empty");
+  });
+
+  it("empty unfiltered corpus: the teaching empty state with an upload CTA", () => {
+    const html = render("", {});
+    expect(html).toContain('data-slot="empty-state"');
+    expect(html).toContain("Your document vault is empty");
+    expect(html).toContain("Upload a first document");
+    expect(html).not.toContain("No matching documents");
+  });
+
+  it("empty filtered view: the distinct no-matches state with clear-filters", () => {
+    const html = render("kind=IMAGING", { kinds: ["IMAGING"] });
+    expect(html).toContain("No matching documents");
+    expect(html).toContain("Clear filters");
+    expect(html).not.toContain("Your document vault is empty");
+  });
+});

src/components/documents/document-filter-bar.tsx

@@ -0,0 +1,202 @@
+"use client";
+
+/**
+ * The vault's sticky filter rail: debounced title/filename search, the
+ * nine-kind type-chip row (multi-select, OR inside the facet), condition
+ * chips (episodes that actually carry links), a year segmenter (years
+ * present in the corpus), and a one-tap clear with the active-facet count.
+ *
+ * Purely presentational — the filter state lives in the page URL and is
+ * owned by `documents-view.tsx`; this bar only renders the controls. It
+ * sticks below the top edge inside the shell's scroll container (sticky,
+ * translucent background, border-b — no viewport-height tricks).
+ */
+import { Search, X } from "lucide-react";
+import type { RefObject } from "react";
+
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { useTranslations } from "@/lib/i18n/context";
+import { cn } from "@/lib/utils";
+import type { InboundDocumentKindValue } from "@/lib/validations/inbound-documents";
+import { DOCUMENT_KIND_ICONS, DOCUMENT_KIND_ORDER } from "./document-kind-meta";
+
+/** Shared chip chrome — mirrors the app-wide FilterBar pill vocabulary. */
+const CHIP_CLASSES =
+  "border-border bg-card text-foreground inline-flex min-h-9 shrink-0 cursor-pointer items-center gap-1.5 rounded-full border px-3 text-sm whitespace-nowrap shadow-xs transition-colors focus-visible:ring-ring/50 focus-visible:ring-[3px] focus-visible:outline-none";
+const CHIP_ACTIVE_CLASSES = "border-primary/40 bg-primary/10";
+
+export interface ConditionChip {
+  episodeId: string;
+  name: string;
+}
+
+export function DocumentFilterBar({
+  searchValue,
+  onSearchChange,
+  searchInputRef,
+  activeKinds,
+  onToggleKind,
+  conditionChips,
+  activeEpisodeId,
+  onToggleEpisode,
+  years,
+  activeYear,
+  onToggleYear,
+  activeCount,
+  onClearAll,
+}: {
+  searchValue: string;
+  onSearchChange: (value: string) => void;
+  /** Focused by the page-level `/` shortcut. */
+  searchInputRef: RefObject<HTMLInputElement | null>;
+  activeKinds: ReadonlySet<InboundDocumentKindValue>;
+  onToggleKind: (kind: InboundDocumentKindValue) => void;
+  conditionChips: ConditionChip[];
+  activeEpisodeId: string | undefined;
+  onToggleEpisode: (episodeId: string) => void;
+  years: number[];
+  activeYear: number | undefined;
+  onToggleYear: (year: number) => void;
+  activeCount: number;
+  onClearAll: () => void;
+}) {
+  const { t } = useTranslations();
+
+  return (
+    <div
+      data-slot="document-filter-bar"
+      className="bg-background/95 border-border sticky top-0 z-10 -mx-4 border-b px-4 pt-1 pb-3 backdrop-blur md:-mx-6 md:px-6"
+    >
+      <div className="flex items-center gap-3">
+        <div className="relative w-full max-w-md">
+          <Search
+            className="text-muted-foreground pointer-events-none absolute top-1/2 left-3 size-4 -translate-y-1/2"
+            aria-hidden
+          />
+          <Input
+            ref={searchInputRef}
+            type="search"
+            value={searchValue}
+            onChange={(e) => onSearchChange(e.target.value)}
+            placeholder={t("documents.filter.searchPlaceholder")}
+            aria-label={t("documents.filter.searchLabel")}
+            className="pr-8 pl-9"
+            aria-keyshortcuts="/"
+          />
+          <kbd
+            aria-hidden
+            className="border-border text-muted-foreground pointer-events-none absolute top-1/2 right-2.5 hidden -translate-y-1/2 rounded border px-1.5 font-mono text-xs sm:inline-block"
+          >
+            /
+          </kbd>
+        </div>
+        {activeCount > 0 ? (
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={onClearAll}
+            className="text-muted-foreground shrink-0"
+          >
+            <X className="size-3.5" aria-hidden />
+            {t("documents.filter.clear")}
+            {activeCount > 1 ? (
+              <span className="tabular-nums">({activeCount})</span>
+            ) : null}
+          </Button>
+        ) : null}
+      </div>
+
+      <div
+        className="-mx-4 mt-3 flex [scrollbar-width:none] items-center gap-2 overflow-x-auto px-4 md:mx-0 md:flex-wrap md:overflow-visible md:px-0 [&::-webkit-scrollbar]:hidden"
+        role="group"
+        aria-label={t("documents.filter.groupLabel")}
+      >
+        <span
+          role="group"
+          aria-label={t("documents.filter.typeGroup")}
+          className="contents"
+        >
+          {DOCUMENT_KIND_ORDER.map((kind) => {
+            const Icon = DOCUMENT_KIND_ICONS[kind];
+            const active = activeKinds.has(kind);
+            return (
+              <button
+                key={kind}
+                type="button"
+                aria-pressed={active}
+                onClick={() => onToggleKind(kind)}
+                className={cn(CHIP_CLASSES, active && CHIP_ACTIVE_CLASSES)}
+              >
+                <Icon className="size-3.5 shrink-0" aria-hidden />
+                {t(`documents.kind.${kind}`)}
+              </button>
+            );
+          })}
+        </span>
+
+        {conditionChips.length > 0 ? (
+          <>
+            <span
+              aria-hidden
+              className="bg-border mx-1 h-5 w-px shrink-0 self-center"
+            />
+            <span
+              role="group"
+              aria-label={t("documents.filter.conditionGroup")}
+              className="contents"
+            >
+              {conditionChips.map((chip) => {
+                const active = chip.episodeId === activeEpisodeId;
+                return (
+                  <button
+                    key={chip.episodeId}
+                    type="button"
+                    aria-pressed={active}
+                    onClick={() => onToggleEpisode(chip.episodeId)}
+                    className={cn(CHIP_CLASSES, active && CHIP_ACTIVE_CLASSES)}
+                  >
+                    <span className="max-w-40 truncate">{chip.name}</span>
+                  </button>
+                );
+              })}
+            </span>
+          </>
+        ) : null}
+
+        {years.length > 0 ? (
+          <>
+            <span
+              aria-hidden
+              className="bg-border mx-1 h-5 w-px shrink-0 self-center"
+            />
+            <span
+              role="group"
+              aria-label={t("documents.filter.yearGroup")}
+              className="contents"
+            >
+              {years.map((year) => {
+                const active = year === activeYear;
+                return (
+                  <button
+                    key={year}
+                    type="button"
+                    aria-pressed={active}
+                    onClick={() => onToggleYear(year)}
+                    className={cn(
+                      CHIP_CLASSES,
+                      "tabular-nums",
+                      active && CHIP_ACTIVE_CLASSES,
+                    )}
+                  >
+                    {year}
+                  </button>
+                );
+              })}
+            </span>
+          </>
+        ) : null}
+      </div>
+    </div>
+  );
+}

src/components/documents/documents-view.tsx

@@ -0,0 +1,414 @@
+"use client";
+
+/**
+ * The Dokumente vault — one wide, calm, filing-cabinet-fast surface.
+ *
+ * Filter state lives in the URL (`?q&kind&episode&year`) so every view is
+ * shareable, back-button-safe, and deep-linkable from the illness page and
+ * labs. Search debounces 200 ms and `/` focuses it. The timeline below is
+ * virtualized; uploads appear optimistically above it in < 100 ms.
+ *
+ * Born-gated on the resolved `modules.inboundDocuments` flag from
+ * `GET /api/auth/me` (per-user opt-in AND the operator availability layer).
+ * An unauthenticated visitor bounces to login; an account without the
+ * module bounces home. Every `/api/documents/inbound/*` route re-enforces
+ * the gate server-side — this is a UX redirect, not the security boundary.
+ */
+import {
+  useInfiniteQuery,
+  useQuery,
+  useQueryClient,
+} from "@tanstack/react-query";
+import { FolderOpen, Loader2, SearchX, Upload, X } from "lucide-react";
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { useIllnessEpisodes } from "@/components/illness/use-illness";
+import { Button } from "@/components/ui/button";
+import { EmptyState } from "@/components/ui/empty-state";
+import { PageHeader } from "@/components/ui/page-header";
+import { QueryErrorCard } from "@/components/ui/query-error-card";
+import { Skeleton } from "@/components/ui/skeleton";
+import { useAuth } from "@/hooks/use-auth";
+import { apiGet } from "@/lib/api/api-fetch";
+import { useTranslations } from "@/lib/i18n/context";
+import { queryKeys } from "@/lib/query-keys";
+import type { DocumentVaultFilters } from "@/lib/query-keys/documents";
+import type {
+  DocumentUsageDto,
+  InboundDocumentDetailDto,
+  InboundDocumentDto,
+  InboundDocumentKindValue,
+} from "@/lib/validations/inbound-documents";
+import { DocumentDetailSheet } from "./document-detail-sheet";
+import { DocumentFilterBar, type ConditionChip } from "./document-filter-bar";
+import { DocumentTimeline } from "./document-timeline";
+import { UploadZone } from "./upload-zone";
+import { useDocumentUpload } from "./use-document-upload";
+import {
+  buildVaultListApiSearch,
+  countActiveFilters,
+  documentDateKey,
+  parseVaultSearchParams,
+  vaultFiltersToSearch,
+} from "./vault-utils";
+
+interface ListPage {
+  documents: InboundDocumentDto[];
+  nextCursor: string | null;
+}
+
+export function DocumentsView() {
+  const { t } = useTranslations();
+  const { user, isLoading: authLoading, isAuthenticated } = useAuth();
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const queryClient = useQueryClient();
+
+  const moduleEnabled = user?.modules?.inboundDocuments === true;
+
+  // UX redirect only — the API routes enforce the gate server-side.
+  useEffect(() => {
+    if (authLoading) return;
+    if (!isAuthenticated) {
+      router.push("/auth/login");
+    } else if (!moduleEnabled) {
+      router.push("/");
+    }
+  }, [authLoading, isAuthenticated, moduleEnabled, router]);
+
+  // ── URL-owned filter state ────────────────────────────────────────────
+  const filters = useMemo(
+    () => parseVaultSearchParams(new URLSearchParams(searchParams.toString())),
+    [searchParams],
+  );
+
+  const applyFilters = useCallback(
+    (next: DocumentVaultFilters, mode: "push" | "replace") => {
+      const search = vaultFiltersToSearch(next);
+      const href = search ? `${pathname}?${search}` : pathname;
+      if (mode === "push") {
+        router.push(href, { scroll: false });
+      } else {
+        router.replace(href, { scroll: false });
+      }
+    },
+    [pathname, router],
+  );
+
+  // Search draft debounces into the URL (200 ms); an external URL change
+  // (back button, deep link) re-seeds the draft — render-phase derived-state
+  // adjustment, not an effect.
+  const [searchDraft, setSearchDraft] = useState(filters.q ?? "");
+  const [lastUrlQ, setLastUrlQ] = useState(filters.q ?? "");
+  const searchInputRef = useRef<HTMLInputElement | null>(null);
+  if ((filters.q ?? "") !== lastUrlQ) {
+    setLastUrlQ(filters.q ?? "");
+    setSearchDraft(filters.q ?? "");
+  }
+  useEffect(() => {
+    const handle = setTimeout(() => {
+      const trimmed = searchDraft.trim();
+      if (trimmed === (filters.q ?? "")) return;
+      applyFilters(
+        { ...filters, q: trimmed === "" ? undefined : trimmed },
+        "replace",
+      );
+    }, 200);
+    return () => clearTimeout(handle);
+  }, [searchDraft, filters, applyFilters]);
+
+  // `/` focuses the search from anywhere on the page.
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "/" || event.metaKey || event.ctrlKey || event.altKey)
+        return;
+      const target = event.target as HTMLElement | null;
+      if (
+        target &&
+        (target.tagName === "INPUT" ||
+          target.tagName === "TEXTAREA" ||
+          target.tagName === "SELECT" ||
+          target.isContentEditable)
+      ) {
+        return;
+      }
+      event.preventDefault();
+      searchInputRef.current?.focus();
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, []);
+
+  const toggleKind = (kind: InboundDocumentKindValue) => {
+    const current = new Set(filters.kinds ?? []);
+    if (current.has(kind)) {
+      current.delete(kind);
+    } else {
+      current.add(kind);
+    }
+    applyFilters(
+      {
+        ...filters,
+        kinds: current.size > 0 ? [...current].sort() : undefined,
+      },
+      "push",
+    );
+  };
+
+  const toggleEpisode = (episodeId: string) => {
+    applyFilters(
+      {
+        ...filters,
+        episodeId: filters.episodeId === episodeId ? undefined : episodeId,
+      },
+      "push",
+    );
+  };
+
+  const toggleYear = (year: number) => {
+    applyFilters(
+      { ...filters, year: filters.year === year ? undefined : year },
+      "push",
+    );
+  };
+
+  const clearFilters = () => {
+    setSearchDraft("");
+    applyFilters({}, "push");
+  };
+
+  // ── Data ──────────────────────────────────────────────────────────────
+  const usage = useQuery({
+    queryKey: queryKeys.inboundDocumentUsage(),
+    enabled: moduleEnabled,
+    queryFn: () => apiGet<DocumentUsageDto>("/api/documents/inbound/usage"),
+  });
+
+  const list = useInfiniteQuery({
+    queryKey: queryKeys.inboundDocumentList(filters),
+    enabled: moduleEnabled,
+    queryFn: ({ pageParam }) =>
+      apiGet<ListPage>(
+        `/api/documents/inbound?${buildVaultListApiSearch(filters, pageParam)}`,
+      ),
+    initialPageParam: null as string | null,
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+  });
+
+  const documents = useMemo(
+    () => list.data?.pages.flatMap((p) => p.documents) ?? [],
+    [list.data],
+  );
+
+  const upload = useDocumentUpload(
+    usage.data ? { maxFileBytes: usage.data.maxFileBytes } : undefined,
+  );
+  const uploadInputRef = useRef<HTMLInputElement | null>(null);
+
+  const episodes = useIllnessEpisodes(true);
+
+  // Condition chips: the user's episodes that actually carry links in the
+  // loaded corpus — plus the actively filtered episode (a deep link must
+  // always show its own chip, even before its documents load).
+  const conditionChips = useMemo<ConditionChip[]>(() => {
+    const byId = new Map<string, string>();
+    for (const doc of documents) {
+      for (const link of doc.conditionLinks) {
+        if (!byId.has(link.episodeId)) byId.set(link.episodeId, link.name);
+      }
+    }
+    if (filters.episodeId && !byId.has(filters.episodeId)) {
+      const episode = episodes.data?.find((e) => e.id === filters.episodeId);
+      byId.set(filters.episodeId, episode?.label ?? filters.episodeId);
+    }
+    return [...byId.entries()]
+      .map(([episodeId, name]) => ({ episodeId, name }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }, [documents, filters.episodeId, episodes.data]);
+
+  // Year segmenter: years present in the loaded corpus (+ the active year).
+  const years = useMemo(() => {
+    const set = new Set<number>();
+    for (const doc of documents) {
+      set.add(Number(documentDateKey(doc).slice(0, 4)));
+    }
+    if (filters.year !== undefined) set.add(filters.year);
+    return [...set].sort((a, b) => b - a);
+  }, [documents, filters.year]);
+
+  // ── Selection (bulk actions attach to this in a follow-up) ───────────
+  const [selectedIds, setSelectedIds] = useState<ReadonlySet<string>>(
+    new Set(),
+  );
+  const toggleSelected = useCallback((id: string) => {
+    setSelectedIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) {
+        next.delete(id);
+      } else {
+        next.add(id);
+      }
+      return next;
+    });
+  }, []);
+
+  // ── Detail sheet ──────────────────────────────────────────────────────
+  const [detailId, setDetailId] = useState<string | null>(null);
+  const [detailOpen, setDetailOpen] = useState(false);
+  const openDetail = useCallback((id: string) => {
+    setDetailId(id);
+    setDetailOpen(true);
+  }, []);
+
+  // Hover/focus intent prefetches the detail METADATA (never the blob —
+  // the blob fetch starts when the sheet mounts its preview element).
+  const prefetchDetail = useCallback(
+    (id: string) => {
+      void queryClient.prefetchQuery({
+        queryKey: queryKeys.inboundDocument(id),
+        queryFn: () =>
+          apiGet<InboundDocumentDetailDto>(`/api/documents/inbound/${id}`),
+        staleTime: 30_000,
+      });
+    },
+    [queryClient],
+  );
+
+  if (authLoading || !isAuthenticated || !moduleEnabled) {
+    return (
+      <div className="flex h-64 items-center justify-center" role="status">
+        <Loader2
+          className="text-primary h-8 w-8 animate-spin motion-reduce:animate-none"
+          aria-hidden
+        />
+        <span className="sr-only">{t("nav.loadingScreen")}</span>
+      </div>
+    );
+  }
+
+  const activeCount = countActiveFilters(filters);
+  const isFiltered = activeCount > 0;
+  const showEmpty =
+    list.isSuccess && documents.length === 0 && upload.items.length === 0;
+
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title={t("documents.title")}
+        description={t("documents.subtitle")}
+        actions={
+          <Button onClick={() => uploadInputRef.current?.click()}>
+            <Upload className="size-4" aria-hidden />
+            {t("documents.pageUpload")}
+          </Button>
+        }
+      />
+
+      <UploadZone
+        usage={usage.data}
+        inputRef={uploadInputRef}
+        onFiles={(files) =>
+          upload.enqueue(files, { episodeId: filters.episodeId })
+        }
+      />
+
+      <DocumentFilterBar
+        searchValue={searchDraft}
+        onSearchChange={setSearchDraft}
+        searchInputRef={searchInputRef}
+        activeKinds={new Set(filters.kinds ?? [])}
+        onToggleKind={toggleKind}
+        conditionChips={conditionChips}
+        activeEpisodeId={filters.episodeId}
+        onToggleEpisode={toggleEpisode}
+        years={years}
+        activeYear={filters.year}
+        onToggleYear={toggleYear}
+        activeCount={activeCount}
+        onClearAll={clearFilters}
+      />
+
+      {selectedIds.size > 0 ? (
+        <div
+          data-slot="document-selection-bar"
+          className="flex items-center justify-between gap-3"
+        >
+          <p className="text-sm font-medium">
+            {t("documents.selection.count", { count: selectedIds.size })}
+          </p>
+          <Button
+            variant="ghost"
+            size="sm"
+            className="text-muted-foreground"
+            onClick={() => setSelectedIds(new Set())}
+          >
+            <X className="size-3.5" aria-hidden />
+            {t("documents.selection.clear")}
+          </Button>
+        </div>
+      ) : null}
+
+      {list.isPending ? (
+        <div
+          data-slot="documents-loading"
+          className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3"
+        >
+          {Array.from({ length: 9 }, (_, i) => (
+            <Skeleton key={i} className="h-28 rounded-xl" />
+          ))}
+        </div>
+      ) : list.isError ? (
+        <QueryErrorCard
+          title={t("documents.list.loadError")}
+          onRetry={() => void list.refetch()}
+        />
+      ) : showEmpty && !isFiltered ? (
+        <EmptyState
+          icon={<FolderOpen className="size-6" aria-hidden />}
+          title={t("documents.empty.title")}
+          description={t("documents.empty.description")}
+          ctaSize="lg"
+          action={
+            <Button onClick={() => uploadInputRef.current?.click()}>
+              <Upload className="size-4" aria-hidden />
+              {t("documents.empty.action")}
+            </Button>
+          }
+        />
+      ) : showEmpty && isFiltered ? (
+        <EmptyState
+          icon={<SearchX className="size-6" aria-hidden />}
+          title={t("documents.empty.noMatchesTitle")}
+          description={t("documents.empty.noMatchesDescription")}
+          action={
+            <Button variant="outline" onClick={clearFilters}>
+              {t("documents.filter.clear")}
+            </Button>
+          }
+        />
+      ) : (
+        <DocumentTimeline
+          documents={documents}
+          uploadItems={upload.items}
+          onDismissUpload={upload.dismiss}
+          hasNextPage={list.hasNextPage}
+          isFetchingNextPage={list.isFetchingNextPage}
+          onLoadMore={() => void list.fetchNextPage()}
+          selectedIds={selectedIds}
+          onToggleSelected={toggleSelected}
+          onOpen={openDetail}
+          highlightId={upload.highlightId}
+          onPrefetch={prefetchDetail}
+        />
+      )}
+
+      <DocumentDetailSheet
+        documentId={detailId}
+        open={detailOpen}
+        onOpenChange={setDetailOpen}
+      />
+    </div>
+  );
+}

src/components/documents/upload-zone.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+/**
+ * The vault's upload entry: a dashed drop-target card with a file button.
+ * The `accept` list comes verbatim from the usage endpoint (HEIC is
+ * deliberately absent so the iOS picker transcodes camera photos to JPEG),
+ * `multiple` is on, and there is NO `capture` attribute — mobile Safari
+ * then offers camera AND library. Dropping files onto the card feeds the
+ * same queue as the picker.
+ *
+ * The quota bar renders only above 80 % usage — a calm surface until
+ * storage actually becomes a topic.
+ */
+import { UploadCloud } from "lucide-react";
+import { useRef, useState, type RefObject } from "react";
+
+import { Button } from "@/components/ui/button";
+import { Progress } from "@/components/ui/progress";
+import { useTranslations } from "@/lib/i18n/context";
+import { cn } from "@/lib/utils";
+import type { DocumentUsageDto } from "@/lib/validations/inbound-documents";
+import { formatBytes } from "./vault-utils";
+
+/** Usage fraction above which the quota bar appears. */
+const QUOTA_BAR_THRESHOLD = 0.8;
+
+export function UploadZone({
+  usage,
+  onFiles,
+  inputRef,
+}: {
+  /** Limits + usage from `GET /api/documents/inbound/usage` (undefined while loading). */
+  usage: DocumentUsageDto | undefined;
+  onFiles: (files: File[]) => void;
+  /** Exposed so the page header's Upload button can open the same picker. */
+  inputRef: RefObject<HTMLInputElement | null>;
+}) {
+  const { t, locale } = useTranslations();
+  const [dragOver, setDragOver] = useState(false);
+  const dragDepth = useRef(0);
+
+  const accept = usage?.acceptedExtensions.join(",");
+  const usedFraction =
+    usage && usage.quotaBytes > 0 ? usage.usedBytes / usage.quotaBytes : 0;
+
+  const pickFiles = (list: FileList | null) => {
+    if (!list || list.length === 0) return;
+    onFiles(Array.from(list));
+  };
+
+  return (
+    <div data-slot="document-upload-zone" className="space-y-2">
+      <div
+        onDragEnter={(e) => {
+          e.preventDefault();
+          dragDepth.current += 1;
+          setDragOver(true);
+        }}
+        onDragOver={(e) => e.preventDefault()}
+        onDragLeave={() => {
+          dragDepth.current = Math.max(0, dragDepth.current - 1);
+          if (dragDepth.current === 0) setDragOver(false);
+        }}
+        onDrop={(e) => {
+          e.preventDefault();
+          dragDepth.current = 0;
+          setDragOver(false);
+          pickFiles(e.dataTransfer.files);
+        }}
+        className={cn(
+          "border-border rounded-xl border-2 border-dashed px-4 py-6 text-center transition-colors",
+          dragOver && "border-primary bg-primary/5",
+        )}
+      >
+        <div className="flex flex-col items-center gap-2">
+          <UploadCloud
+            className={cn(
+              "text-muted-foreground size-6",
+              dragOver && "text-primary",
+            )}
+            aria-hidden
+          />
+          <p className="text-sm font-medium">
+            {t("documents.upload.zoneTitle")}
+          </p>
+          {usage ? (
+            <p className="text-muted-foreground text-xs">
+              {t("documents.upload.zoneHint", {
+                maxSize: formatBytes(usage.maxFileBytes, locale),
+              })}
+            </p>
+          ) : null}
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className="mt-1"
+            onClick={() => inputRef.current?.click()}
+          >
+            {t("documents.upload.browse")}
+          </Button>
+        </div>
+        <input
+          ref={inputRef}
+          type="file"
+          multiple
+          accept={accept}
+          className="sr-only"
+          aria-label={t("documents.upload.browse")}
+          onChange={(e) => {
+            pickFiles(e.target.files);
+            // Allow re-selecting the same file (duplicate flow) immediately.
+            e.target.value = "";
+          }}
+        />
+      </div>
+
+      {usage && usedFraction >= QUOTA_BAR_THRESHOLD ? (
+        <div data-slot="document-quota-bar" className="space-y-1">
+          <div className="flex items-center justify-between gap-3">
+            <p className="text-sm font-medium">
+              {t("documents.upload.quotaAlmostFull")}
+            </p>
+            <p className="text-muted-foreground text-xs tabular-nums">
+              {t("documents.upload.quotaUsed", {
+                used: formatBytes(usage.usedBytes, locale),
+                quota: formatBytes(usage.quotaBytes, locale),
+              })}
+            </p>
+          </div>
+          <Progress
+            value={Math.min(100, usedFraction * 100)}
+            aria-label={t("documents.upload.quotaUsed", {
+              used: formatBytes(usage.usedBytes, locale),
+              quota: formatBytes(usage.quotaBytes, locale),
+            })}
+          />
+        </div>
+      ) : null}
+    </div>
+  );
+}

src/components/layout/auth-shell.tsx

@@ -36,6 +36,13 @@ const PUBLIC_PATHS = [
   "/c/",
 ];
 
+// Routes that opt into the wide content container (`max-w-screen-2xl`
+// instead of the standard `max-w-screen-xl`). The shell stays the single
+// owner of the page frame — a wide page never re-implements paddings or
+// margins; it is listed here instead. Currently: the Dokumente vault,
+// whose multi-column document timeline earns the extra width.
+const WIDE_CONTENT_PATHS = ["/documents"];
+
 export function AuthShell({
   children,
   demoMode = false,
@@ -69,6 +76,9 @@ export function AuthShell({
     pathname.startsWith("/about") ||
     pathname.startsWith("/c/");
   const isAdminPage = pathname.startsWith("/admin");
+  const isWidePage = WIDE_CONTENT_PATHS.some(
+    (p) => pathname === p || pathname.startsWith(`${p}/`),
+  );
   const isOnboardingPage = pathname === "/onboarding";
   const showUnlockNotifier = isAuthenticated && !isPublicPage && !!user?.id;
 
@@ -315,7 +325,13 @@ export function AuthShell({
               the desktop bottom-6 anchor), so the last line of content
               can always scroll out from under the floating button.
             */}
-            <div className="mx-auto max-w-screen-xl px-4 pt-6 pb-20 md:px-6">
+            <div
+              className={
+                isWidePage
+                  ? "mx-auto max-w-screen-2xl px-4 pt-6 pb-20 md:px-6"
+                  : "mx-auto max-w-screen-xl px-4 pt-6 pb-20 md:px-6"
+              }
+            >
               {children}
             </div>
           </main>