From e64dbc08d5d26093f51ee8d6664d91af155ac72c Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Wed, 22 Jul 2026 11:40:13 +0800
Subject: [PATCH 1/4] feat(upload): reject over-limit files in the browser
 before transferring (FV-04)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An over-limit guideline PDF was transferred in full before the server
answered 413 — on a large file over a clinic connection that is a long
wait for a guaranteed rejection, with the limit itself never stated
anywhere in the UI.

- New dependency-free `src/lib/upload-limits.ts` holds the ceiling so a
  client component can import it; `src/lib/http.ts` (next/server) and
  `src/lib/env.ts` (server-only secrets) both can't cross into the bundle.
- `env.MAX_UPLOAD_MB` now derives its cap and default from that constant,
  so the configured limit can only ever be *lower* than what the client
  rejects up front — the pre-check can never refuse a file the server
  would have accepted, and the server stays the authority.
- `UploadPanel` skips an over-ceiling file with the server's own 413
  wording (shared message builder, so the two can't diverge) and still
  uploads the rest of the batch, matching per-file outcome semantics.
- The file field states "PDF only, up to 150 MB per file", wired via
  aria-describedby so it is announced, not just visible.

The ingress pin in tests/upload-ingress-limits.test.ts now asserts the
constant's value plus env's derivation from it, keeping the 151mb proxy
envelope tied to the same number.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../DocumentManagerPanel.tsx                  |  24 +++-
 src/lib/env.ts                                |   5 +-
 src/lib/http.ts                               |   3 +-
 src/lib/upload-limits.ts                      |  32 +++++
 tests/upload-ingress-limits.test.ts           |  10 +-
 tests/upload-size-precheck.dom.test.tsx       | 129 ++++++++++++++++++
 6 files changed, 199 insertions(+), 4 deletions(-)
 create mode 100644 src/lib/upload-limits.ts
 create mode 100644 tests/upload-size-precheck.dom.test.tsx

diff --git a/src/components/clinical-dashboard/DocumentManagerPanel.tsx b/src/components/clinical-dashboard/DocumentManagerPanel.tsx
index 9f8bff1d38..545d8eb2de 100644
--- a/src/components/clinical-dashboard/DocumentManagerPanel.tsx
+++ b/src/components/clinical-dashboard/DocumentManagerPanel.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useRef } from "react";
+import { useState, useRef, useId } from "react";
 import Link from "next/link";
 import { UploadCloud, Loader2, RefreshCw, Sparkles, ShieldCheck, ExternalLink } from "lucide-react";
 import {
@@ -19,6 +19,7 @@ import {
 } from "@/components/ui-primitives";
 import { cleanDisplayTitle } from "@/components/clinical-dashboard/display-text";
 import { emptyStates, errorCopy } from "@/lib/ui-copy";
+import { MAX_UPLOAD_MB_CEILING, exceedsUploadSizeCeiling, uploadSizeLimitMessage } from "@/lib/upload-limits";
 import { StatusBadge } from "@/components/clinical-dashboard/badges";
 import { PrivacyInputNotice } from "@/components/privacy-input-notice";
 import type { ClinicalDocument, IngestionJob, ImportBatch } from "@/lib/types";
@@ -299,6 +300,7 @@ export function UploadPanel({
   const [uploadPercent, setUploadPercent] = useState<number | null>(null);
   const [localStatus, setLocalStatus] = useState<string | null>(null);
   const fileInputRef = useRef<HTMLInputElement | null>(null);
+  const fileHintId = useId();
 
   const displayStatus = status !== undefined ? status : localStatus;
   const changeStatus = setStatus || setLocalStatus;
@@ -333,6 +335,22 @@ export function UploadPanel({
     for (let index = 0; index < files.length; index++) {
       const file = files[index];
       try {
+        // Pre-check the size before spending the transfer. The server caps every
+        // file at env.MAX_UPLOAD_MB, which its schema can never raise above
+        // MAX_UPLOAD_MB_CEILING, so an over-ceiling file is a guaranteed 413 —
+        // uploading it first only makes the clinician wait for the rejection.
+        // The rest of the batch still uploads, matching the server's per-file
+        // outcome semantics.
+        if (exceedsUploadSizeCeiling(file.size)) {
+          outcomes.push({
+            kind: "failed",
+            fileName: file.name,
+            status: 413,
+            code: "payload_too_large",
+            message: uploadSizeLimitMessage(MAX_UPLOAD_MB_CEILING),
+          });
+          continue;
+        }
         changeStatus(
           files.length === 1 ? `Uploading ${file.name}...` : `Uploading ${index + 1} of ${files.length}: ${file.name}`,
         );
@@ -400,10 +418,14 @@ export function UploadPanel({
           accept=".pdf,application/pdf"
           multiple
           disabled={demoMode || !canUpload || uploading}
+          aria-describedby={fileHintId}
           onChange={() => changeStatus(null)}
           className="mt-2 block w-full text-xs font-medium text-[color:var(--text-muted)] file:mr-3 file:min-h-9 file:cursor-pointer file:rounded-md file:border file:border-[color:var(--border)] file:bg-[color:var(--surface)] file:px-3 file:text-xs file:font-semibold file:text-[color:var(--text)] file:shadow-[var(--shadow-inset)] file:transition file:hover:bg-[color:var(--surface-subtle)] disabled:opacity-50"
         />
       </label>
+      <p id={fileHintId} className={cn(textMuted, "mt-2 text-xs")}>
+        PDF only, up to {MAX_UPLOAD_MB_CEILING} MB per file.
+      </p>
       <div className="mt-3">
         <button
           type="submit"
diff --git a/src/lib/env.ts b/src/lib/env.ts
index 92f5b060ee..2441449b29 100644
--- a/src/lib/env.ts
+++ b/src/lib/env.ts
@@ -3,6 +3,7 @@ import "server-only";
 import { z } from "zod";
 import { resolvePythonBin } from "@/lib/python-bin";
 import { assertExpectedSupabaseProjectConfig, checkSupabaseProjectConfig } from "@/lib/supabase/project";
+import { MAX_UPLOAD_MB_CEILING } from "@/lib/upload-limits";
 
 const envSchema = z.object({
   NEXT_PUBLIC_SUPABASE_URL: z.string().url().optional(),
@@ -189,7 +190,9 @@ const envSchema = z.object({
   RAG_QUERY_HASH_SECRET: z.string().min(16).optional(),
   SUPABASE_DOCUMENT_BUCKET: z.string().default("clinical-documents"),
   SUPABASE_IMAGE_BUCKET: z.string().default("clinical-images"),
-  MAX_UPLOAD_MB: z.coerce.number().int().positive().max(150).default(150),
+  // Capped at the ceiling the browser pre-checks against, so a configured limit
+  // can only ever be lower than what the client rejects up front.
+  MAX_UPLOAD_MB: z.coerce.number().int().positive().max(MAX_UPLOAD_MB_CEILING).default(MAX_UPLOAD_MB_CEILING),
   MAX_CONCURRENT_UPLOADS: z.coerce.number().int().positive().default(1),
   MAX_IN_FLIGHT_UPLOAD_MB: z.coerce.number().int().positive().default(151),
   MAX_IMPORT_JOBS_PER_RUN: z.coerce.number().int().positive().default(5),
diff --git a/src/lib/http.ts b/src/lib/http.ts
index 7daeaa6b81..d98c437671 100644
--- a/src/lib/http.ts
+++ b/src/lib/http.ts
@@ -2,6 +2,7 @@ import { NextResponse } from "next/server";
 import { ZodError } from "zod";
 import { logger } from "@/lib/logger";
 import { safeErrorLogDetails } from "@/lib/privacy";
+import { uploadSizeLimitMessage } from "@/lib/upload-limits";
 
 export class PublicApiError extends Error {
   constructor(
@@ -88,7 +89,7 @@ export function assertAllowedFile(file: File, maxUploadMb: number) {
 
   const maxBytes = maxUploadMb * 1024 * 1024;
   if (file.size > maxBytes) {
-    throw new PublicApiError(`File exceeds ${maxUploadMb} MB upload limit.`, 413, { code: "payload_too_large" });
+    throw new PublicApiError(uploadSizeLimitMessage(maxUploadMb), 413, { code: "payload_too_large" });
   }
 }
 
diff --git a/src/lib/upload-limits.ts b/src/lib/upload-limits.ts
new file mode 100644
index 0000000000..5cc3860782
--- /dev/null
+++ b/src/lib/upload-limits.ts
@@ -0,0 +1,32 @@
+/**
+ * Upload size limits shared by the browser and the API route.
+ *
+ * This module is deliberately dependency-free so a client component can import
+ * it: `src/lib/http.ts` (the authoritative check) pulls in `next/server`, and
+ * `src/lib/env.ts` holds server-only secrets, so neither can cross into the
+ * bundle.
+ *
+ * The server's effective limit is `env.MAX_UPLOAD_MB`, whose schema caps it at
+ * `MAX_UPLOAD_MB_CEILING` — an operator can configure a *lower* limit, never a
+ * higher one. A browser-side pre-check at the ceiling therefore only ever
+ * rejects a file the server was certain to reject too; anything under it is
+ * still sent, and the server remains the authority.
+ */
+
+/** Hard ceiling for a single uploaded file, in MB. */
+export const MAX_UPLOAD_MB_CEILING = 150;
+
+const BYTES_PER_MB = 1024 * 1024;
+
+/** True when a file is larger than any limit the server can be configured to accept. */
+export function exceedsUploadSizeCeiling(sizeInBytes: number): boolean {
+  return sizeInBytes > MAX_UPLOAD_MB_CEILING * BYTES_PER_MB;
+}
+
+/**
+ * The single wording for an over-limit file, so the pre-check reads exactly the
+ * same as the server's 413 rather than inventing a second phrasing.
+ */
+export function uploadSizeLimitMessage(maxUploadMb: number): string {
+  return `File exceeds ${maxUploadMb} MB upload limit.`;
+}
diff --git a/tests/upload-ingress-limits.test.ts b/tests/upload-ingress-limits.test.ts
index 60281c7848..47c2328bfd 100644
--- a/tests/upload-ingress-limits.test.ts
+++ b/tests/upload-ingress-limits.test.ts
@@ -1,6 +1,8 @@
 import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 
+import { MAX_UPLOAD_MB_CEILING } from "../src/lib/upload-limits";
+
 const nextConfig = readFileSync(new URL("../next.config.ts", import.meta.url), "utf8");
 const proxySource = readFileSync(new URL("../src/proxy.ts", import.meta.url), "utf8");
 const envSource = readFileSync(new URL("../src/lib/env.ts", import.meta.url), "utf8");
@@ -11,6 +13,12 @@ describe("upload ingress budgets", () => {
     expect(proxySource).toContain('request.nextUrl.pathname === "/api/upload"');
     expect(proxySource).toContain("declaredLength > uploadEnvelopeBytes");
     expect(proxySource).toContain("status: 413");
-    expect(envSource).toContain("MAX_UPLOAD_MB: z.coerce.number().int().positive().max(150).default(150)");
+    // The 151mb proxy envelope is the ceiling plus 1mb of multipart overhead,
+    // and the browser pre-check rejects above the same ceiling — so pin both
+    // the value and that env derives its cap from it rather than a second literal.
+    expect(MAX_UPLOAD_MB_CEILING).toBe(150);
+    expect(envSource).toContain(
+      "MAX_UPLOAD_MB: z.coerce.number().int().positive().max(MAX_UPLOAD_MB_CEILING).default(MAX_UPLOAD_MB_CEILING)",
+    );
   });
 });
diff --git a/tests/upload-size-precheck.dom.test.tsx b/tests/upload-size-precheck.dom.test.tsx
new file mode 100644
index 0000000000..8bc1fc3d51
--- /dev/null
+++ b/tests/upload-size-precheck.dom.test.tsx
@@ -0,0 +1,129 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { UploadPanel } from "@/components/clinical-dashboard/DocumentManagerPanel";
+import { MAX_UPLOAD_MB_CEILING } from "@/lib/upload-limits";
+
+// The upload API caps every file at env.MAX_UPLOAD_MB, which its schema can
+// never raise above MAX_UPLOAD_MB_CEILING (src/lib/env.ts). Without a browser
+// pre-check an over-ceiling file is transferred in full before the server
+// answers 413 — on a large guideline PDF over a clinic connection that is a
+// long wait for a guaranteed rejection. These tests pin that the pre-check
+// fires locally, that it does NOT swallow files the server might still accept,
+// and that a mixed batch still uploads its valid files.
+
+type OpenedRequest = { method: string; url: string };
+
+const opened: OpenedRequest[] = [];
+
+class FakeXhr {
+  static lastStatus = 200;
+  static lastResponse = JSON.stringify({ document: { id: "doc-1" }, job: { id: "job-1" } });
+
+  upload = { onprogress: null as ((event: ProgressEvent) => void) | null };
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  onabort: (() => void) | null = null;
+  status = 0;
+  responseText = "";
+
+  open(method: string, url: string) {
+    opened.push({ method, url });
+  }
+  setRequestHeader() {}
+  abort() {}
+  send() {
+    this.status = FakeXhr.lastStatus;
+    this.responseText = FakeXhr.lastResponse;
+    // Resolve on a microtask so the component's await actually suspends first.
+    queueMicrotask(() => this.onload?.());
+  }
+}
+
+function fileOfSize(name: string, megabytes: number): File {
+  // Allocating the real bytes would cost hundreds of MB; only `size` is read.
+  const file = new File(["stub"], name, { type: "application/pdf" });
+  Object.defineProperty(file, "size", { value: Math.round(megabytes * 1024 * 1024) });
+  return file;
+}
+
+function renderPanel() {
+  const onUploaded = vi.fn();
+  render(
+    <UploadPanel
+      onUploaded={onUploaded}
+      demoMode={false}
+      canUpload
+      authorizationHeader={{ Authorization: "Bearer t" }}
+    />,
+  );
+  return { onUploaded };
+}
+
+function selectFiles(files: File[]) {
+  const input = screen.getByLabelText(/Guideline PDF files/i);
+  fireEvent.change(input, { target: { files } });
+}
+
+function submit() {
+  fireEvent.click(screen.getByRole("button", { name: "Upload guidelines" }));
+}
+
+beforeEach(() => {
+  opened.length = 0;
+  FakeXhr.lastStatus = 200;
+  FakeXhr.lastResponse = JSON.stringify({ document: { id: "doc-1" }, job: { id: "job-1" } });
+  vi.stubGlobal("XMLHttpRequest", FakeXhr);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("upload size pre-check", () => {
+  it("surfaces the limit on the file field before anything is selected", () => {
+    renderPanel();
+    const hint = screen.getByText(`PDF only, up to ${MAX_UPLOAD_MB_CEILING} MB per file.`);
+    expect(hint).toBeVisible();
+    // The limit must be announced to assistive tech from the input itself, not
+    // just sit next to it as visual text.
+    const input = screen.getByLabelText(/Guideline PDF files/i);
+    expect(input.getAttribute("aria-describedby")).toBe(hint.id);
+  });
+
+  it("rejects an over-ceiling file locally, without opening a request", async () => {
+    const { onUploaded } = renderPanel();
+    selectFiles([fileOfSize("huge-guideline.pdf", MAX_UPLOAD_MB_CEILING + 1)]);
+    submit();
+
+    expect(await screen.findByText(/huge-guideline\.pdf/)).toHaveTextContent(
+      `File exceeds ${MAX_UPLOAD_MB_CEILING} MB upload limit.`,
+    );
+    expect(opened).toHaveLength(0);
+    // A batch with no accepted file must not claim the library changed.
+    expect(onUploaded).not.toHaveBeenCalled();
+  });
+
+  it("still uploads a file at the ceiling — the server owns the real limit", async () => {
+    const { onUploaded } = renderPanel();
+    selectFiles([fileOfSize("at-limit.pdf", MAX_UPLOAD_MB_CEILING)]);
+    submit();
+
+    expect(await screen.findByText(/queued for indexing/)).toBeVisible();
+    expect(opened).toEqual([{ method: "POST", url: "/api/upload" }]);
+    expect(onUploaded).toHaveBeenCalledTimes(1);
+  });
+
+  it("uploads the valid files in a mixed batch and reports the skipped one", async () => {
+    renderPanel();
+    selectFiles([fileOfSize("huge-guideline.pdf", MAX_UPLOAD_MB_CEILING * 2), fileOfSize("ok-guideline.pdf", 2)]);
+    submit();
+
+    const status = await screen.findByText(/Upload complete/);
+    expect(status).toHaveTextContent("1 accepted; 1 failed");
+    expect(status).toHaveTextContent(`huge-guideline.pdf: File exceeds ${MAX_UPLOAD_MB_CEILING} MB upload limit.`);
+    // Exactly one request: the oversized file never reached the network.
+    expect(opened).toHaveLength(1);
+  });
+});

From c947c9288c799d3c7624d0eac9ea17ae952dc2ff Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Wed, 22 Jul 2026 13:57:42 +0800
Subject: [PATCH 2/4] fix(upload): align client precheck with optional public
 max MB

Expose NEXT_PUBLIC_MAX_UPLOAD_MB via getClientMaxUploadMb() so DocumentManagerPanel rejects/hints at a lowered operator limit instead of always using the 150 MB ceiling; server env.MAX_UPLOAD_MB remains authoritative.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .env.example                                  |  4 +++
 .../DocumentManagerPanel.tsx                  | 24 ++++++++++-------
 src/lib/upload-limits.ts                      | 26 ++++++++++++++++---
 tests/upload-size-precheck.dom.test.tsx       | 24 +++++++++++++++--
 4 files changed, 63 insertions(+), 15 deletions(-)

diff --git a/.env.example b/.env.example
index 681061da59..14361ca553 100644
--- a/.env.example
+++ b/.env.example
@@ -162,6 +162,10 @@ SUPABASE_IMAGE_BUCKET=clinical-images
 # Conservative local-first defaults. Raise only after testing your worker machine,
 # Supabase plan limits, and confidentiality policy.
 MAX_UPLOAD_MB=150
+# Optional browser mirror of MAX_UPLOAD_MB. When you lower MAX_UPLOAD_MB, set
+# the same value here so the Document Manager pre-check and hint match the
+# server before a large transfer starts. Clamped to 150; unset falls back to 150.
+# NEXT_PUBLIC_MAX_UPLOAD_MB=150
 # Next Proxy has a fixed 151 MiB transport envelope (150 MiB file plus
 # multipart framing), so values above 150 are intentionally rejected.
 MAX_CONCURRENT_UPLOADS=1
diff --git a/src/components/clinical-dashboard/DocumentManagerPanel.tsx b/src/components/clinical-dashboard/DocumentManagerPanel.tsx
index 545d8eb2de..99de8c5936 100644
--- a/src/components/clinical-dashboard/DocumentManagerPanel.tsx
+++ b/src/components/clinical-dashboard/DocumentManagerPanel.tsx
@@ -19,7 +19,11 @@ import {
 } from "@/components/ui-primitives";
 import { cleanDisplayTitle } from "@/components/clinical-dashboard/display-text";
 import { emptyStates, errorCopy } from "@/lib/ui-copy";
-import { MAX_UPLOAD_MB_CEILING, exceedsUploadSizeCeiling, uploadSizeLimitMessage } from "@/lib/upload-limits";
+import {
+  exceedsClientUploadSize,
+  getClientMaxUploadMb,
+  uploadSizeLimitMessage,
+} from "@/lib/upload-limits";
 import { StatusBadge } from "@/components/clinical-dashboard/badges";
 import { PrivacyInputNotice } from "@/components/privacy-input-notice";
 import type { ClinicalDocument, IngestionJob, ImportBatch } from "@/lib/types";
@@ -335,19 +339,19 @@ export function UploadPanel({
     for (let index = 0; index < files.length; index++) {
       const file = files[index];
       try {
-        // Pre-check the size before spending the transfer. The server caps every
-        // file at env.MAX_UPLOAD_MB, which its schema can never raise above
-        // MAX_UPLOAD_MB_CEILING, so an over-ceiling file is a guaranteed 413 —
-        // uploading it first only makes the clinician wait for the rejection.
-        // The rest of the batch still uploads, matching the server's per-file
-        // outcome semantics.
-        if (exceedsUploadSizeCeiling(file.size)) {
+        // Pre-check the size before spending the transfer. Prefer
+        // NEXT_PUBLIC_MAX_UPLOAD_MB (clamped to the ceiling) so a lowered
+        // operator limit matches the UI; the server still enforces
+        // env.MAX_UPLOAD_MB as the authority. The rest of the batch still
+        // uploads, matching the server's per-file outcome semantics.
+        const clientMaxUploadMb = getClientMaxUploadMb();
+        if (exceedsClientUploadSize(file.size)) {
           outcomes.push({
             kind: "failed",
             fileName: file.name,
             status: 413,
             code: "payload_too_large",
-            message: uploadSizeLimitMessage(MAX_UPLOAD_MB_CEILING),
+            message: uploadSizeLimitMessage(clientMaxUploadMb),
           });
           continue;
         }
@@ -424,7 +428,7 @@ export function UploadPanel({
         />
       </label>
       <p id={fileHintId} className={cn(textMuted, "mt-2 text-xs")}>
-        PDF only, up to {MAX_UPLOAD_MB_CEILING} MB per file.
+        PDF only, up to {getClientMaxUploadMb()} MB per file.
       </p>
       <div className="mt-3">
         <button
diff --git a/src/lib/upload-limits.ts b/src/lib/upload-limits.ts
index 5cc3860782..ad2be7266e 100644
--- a/src/lib/upload-limits.ts
+++ b/src/lib/upload-limits.ts
@@ -8,9 +8,10 @@
  *
  * The server's effective limit is `env.MAX_UPLOAD_MB`, whose schema caps it at
  * `MAX_UPLOAD_MB_CEILING` — an operator can configure a *lower* limit, never a
- * higher one. A browser-side pre-check at the ceiling therefore only ever
- * rejects a file the server was certain to reject too; anything under it is
- * still sent, and the server remains the authority.
+ * higher one. The browser pre-check reads optional `NEXT_PUBLIC_MAX_UPLOAD_MB`
+ * (clamped to the same ceiling) so the UI can match a lowered server limit;
+ * when that public env is unset it falls back to the ceiling. The server
+ * remains the authority for anything that still reaches `/api/upload`.
  */
 
 /** Hard ceiling for a single uploaded file, in MB. */
@@ -18,6 +19,25 @@ export const MAX_UPLOAD_MB_CEILING = 150;
 
 const BYTES_PER_MB = 1024 * 1024;
 
+/**
+ * Effective client-side upload limit in MB.
+ * Reads `NEXT_PUBLIC_MAX_UPLOAD_MB` when set to a positive integer, clamps to
+ * the ceiling, and otherwise uses the ceiling (safe default when operators
+ * have not mirrored a lowered `MAX_UPLOAD_MB`).
+ */
+export function getClientMaxUploadMb(): number {
+  const raw = process.env.NEXT_PUBLIC_MAX_UPLOAD_MB?.trim();
+  if (!raw) return MAX_UPLOAD_MB_CEILING;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1) return MAX_UPLOAD_MB_CEILING;
+  return Math.min(parsed, MAX_UPLOAD_MB_CEILING);
+}
+
+/** True when a file exceeds the effective client pre-check limit. */
+export function exceedsClientUploadSize(sizeInBytes: number): boolean {
+  return sizeInBytes > getClientMaxUploadMb() * BYTES_PER_MB;
+}
+
 /** True when a file is larger than any limit the server can be configured to accept. */
 export function exceedsUploadSizeCeiling(sizeInBytes: number): boolean {
   return sizeInBytes > MAX_UPLOAD_MB_CEILING * BYTES_PER_MB;
diff --git a/tests/upload-size-precheck.dom.test.tsx b/tests/upload-size-precheck.dom.test.tsx
index 8bc1fc3d51..5bf68cdf45 100644
--- a/tests/upload-size-precheck.dom.test.tsx
+++ b/tests/upload-size-precheck.dom.test.tsx
@@ -9,8 +9,10 @@ import { MAX_UPLOAD_MB_CEILING } from "@/lib/upload-limits";
 // pre-check an over-ceiling file is transferred in full before the server
 // answers 413 — on a large guideline PDF over a clinic connection that is a
 // long wait for a guaranteed rejection. These tests pin that the pre-check
-// fires locally, that it does NOT swallow files the server might still accept,
-// and that a mixed batch still uploads its valid files.
+// fires locally (using NEXT_PUBLIC_MAX_UPLOAD_MB when set, else the ceiling),
+// that it does NOT swallow files the effective client limit still accepts,
+// and that a mixed batch still uploads its valid files. The server remains
+// the authority via env.MAX_UPLOAD_MB for anything that reaches /api/upload.
 
 type OpenedRequest = { method: string; url: string };
 
@@ -74,10 +76,12 @@ beforeEach(() => {
   FakeXhr.lastStatus = 200;
   FakeXhr.lastResponse = JSON.stringify({ document: { id: "doc-1" }, job: { id: "job-1" } });
   vi.stubGlobal("XMLHttpRequest", FakeXhr);
+  vi.unstubAllEnvs();
 });
 
 afterEach(() => {
   vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
   vi.restoreAllMocks();
 });
 
@@ -126,4 +130,20 @@ describe("upload size pre-check", () => {
     // Exactly one request: the oversized file never reached the network.
     expect(opened).toHaveLength(1);
   });
+
+  it("honours a lowered NEXT_PUBLIC_MAX_UPLOAD_MB for the hint and pre-check", async () => {
+    vi.stubEnv("NEXT_PUBLIC_MAX_UPLOAD_MB", "50");
+    const { onUploaded } = renderPanel();
+
+    expect(screen.getByText("PDF only, up to 50 MB per file.")).toBeVisible();
+
+    selectFiles([fileOfSize("mid-guideline.pdf", 51)]);
+    submit();
+
+    expect(await screen.findByText(/mid-guideline\.pdf/)).toHaveTextContent(
+      "File exceeds 50 MB upload limit.",
+    );
+    expect(opened).toHaveLength(0);
+    expect(onUploaded).not.toHaveBeenCalled();
+  });
 });

From c023b92fa1fdb3ba49ec1c64b26f35c75b2d990c Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Wed, 22 Jul 2026 13:58:16 +0800
Subject: [PATCH 3/4] style(upload): prettier-format DocumentManagerPanel
 precheck changes

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 src/components/clinical-dashboard/DocumentManagerPanel.tsx | 6 +-----
 tests/upload-size-precheck.dom.test.tsx                    | 4 +---
 2 files changed, 2 insertions(+), 8 deletions(-)

diff --git a/src/components/clinical-dashboard/DocumentManagerPanel.tsx b/src/components/clinical-dashboard/DocumentManagerPanel.tsx
index 99de8c5936..0f2d284010 100644
--- a/src/components/clinical-dashboard/DocumentManagerPanel.tsx
+++ b/src/components/clinical-dashboard/DocumentManagerPanel.tsx
@@ -19,11 +19,7 @@ import {
 } from "@/components/ui-primitives";
 import { cleanDisplayTitle } from "@/components/clinical-dashboard/display-text";
 import { emptyStates, errorCopy } from "@/lib/ui-copy";
-import {
-  exceedsClientUploadSize,
-  getClientMaxUploadMb,
-  uploadSizeLimitMessage,
-} from "@/lib/upload-limits";
+import { exceedsClientUploadSize, getClientMaxUploadMb, uploadSizeLimitMessage } from "@/lib/upload-limits";
 import { StatusBadge } from "@/components/clinical-dashboard/badges";
 import { PrivacyInputNotice } from "@/components/privacy-input-notice";
 import type { ClinicalDocument, IngestionJob, ImportBatch } from "@/lib/types";
diff --git a/tests/upload-size-precheck.dom.test.tsx b/tests/upload-size-precheck.dom.test.tsx
index 5bf68cdf45..7ef85ec6bd 100644
--- a/tests/upload-size-precheck.dom.test.tsx
+++ b/tests/upload-size-precheck.dom.test.tsx
@@ -140,9 +140,7 @@ describe("upload size pre-check", () => {
     selectFiles([fileOfSize("mid-guideline.pdf", 51)]);
     submit();
 
-    expect(await screen.findByText(/mid-guideline\.pdf/)).toHaveTextContent(
-      "File exceeds 50 MB upload limit.",
-    );
+    expect(await screen.findByText(/mid-guideline\.pdf/)).toHaveTextContent("File exceeds 50 MB upload limit.");
     expect(opened).toHaveLength(0);
     expect(onUploaded).not.toHaveBeenCalled();
   });

From 2f3b2b845d9ce0031d889e98024724437da05da7 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Wed, 22 Jul 2026 16:52:21 +0800
Subject: [PATCH 4/4] fix(upload): wire public max MB through Docker builds and
 pin DOM tests

Add NEXT_PUBLIC_MAX_UPLOAD_MB ARG/ENV + CI build-arg so lowered upload
limits inline at image build time, and stub the env empty in default
DOM cases so inherited shell values cannot flake the 150 MB assertions.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .env.example                            | 2 ++
 .github/workflows/docker-image.yml      | 1 +
 Dockerfile                              | 6 ++++++
 docs/deployment-architecture.md         | 6 ++++++
 tests/upload-size-precheck.dom.test.tsx | 3 +++
 5 files changed, 18 insertions(+)

diff --git a/.env.example b/.env.example
index 14361ca553..9d1e14c4d0 100644
--- a/.env.example
+++ b/.env.example
@@ -165,6 +165,8 @@ MAX_UPLOAD_MB=150
 # Optional browser mirror of MAX_UPLOAD_MB. When you lower MAX_UPLOAD_MB, set
 # the same value here so the Document Manager pre-check and hint match the
 # server before a large transfer starts. Clamped to 150; unset falls back to 150.
+# For Railway/Docker production images this is a BUILD-TIME variable (Dockerfile
+# ARG/ENV before npm run build) — mirror lowered MAX_UPLOAD_MB before rebuilding.
 # NEXT_PUBLIC_MAX_UPLOAD_MB=150
 # Next Proxy has a fixed 151 MiB transport envelope (150 MiB file plus
 # multipart framing), so values above 150 are intentionally rejected.
diff --git a/.github/workflows/docker-image.yml b/.github/workflows/docker-image.yml
index d8186ed458..a74792aa54 100644
--- a/.github/workflows/docker-image.yml
+++ b/.github/workflows/docker-image.yml
@@ -74,6 +74,7 @@ jobs:
           build-args: |
             NEXT_PUBLIC_SUPABASE_URL=https://sjrfecxgysukkwxsowpy.supabase.co
             NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=placeholder-ci-publishable-key
+            NEXT_PUBLIC_MAX_UPLOAD_MB=
 
   worker-image:
     runs-on: ubuntu-24.04
diff --git a/Dockerfile b/Dockerfile
index 94b6cc5486..6f2537677f 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -11,6 +11,7 @@
 # production image:
 #   docker build \
 #     --build-arg NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_... \
+#     --build-arg NEXT_PUBLIC_MAX_UPLOAD_MB=150 \
 #     -t clinical-kb-app .
 # Server-side secrets (SUPABASE_SERVICE_ROLE_KEY, OPENAI_API_KEY, ...) are
 # NEVER baked into the image — inject them at run time from the host's
@@ -33,8 +34,13 @@ COPY --from=deps /app/node_modules ./node_modules
 COPY . .
 ARG NEXT_PUBLIC_SUPABASE_URL=https://sjrfecxgysukkwxsowpy.supabase.co
 ARG NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=placeholder-build-publishable-key
+# Optional browser upload-limit mirror (clamped client-side). Must be set at
+# build time to inline into the client bundle — runtime Railway vars alone are
+# not enough when operators lower MAX_UPLOAD_MB.
+ARG NEXT_PUBLIC_MAX_UPLOAD_MB=
 ENV NEXT_PUBLIC_SUPABASE_URL=${NEXT_PUBLIC_SUPABASE_URL}
 ENV NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=${NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY}
+ENV NEXT_PUBLIC_MAX_UPLOAD_MB=${NEXT_PUBLIC_MAX_UPLOAD_MB}
 # The repo build script allocates an 8 GiB heap; give the builder >= 10 GiB.
 RUN npm run build
 
diff --git a/docs/deployment-architecture.md b/docs/deployment-architecture.md
index f812d44b25..67f642e614 100644
--- a/docs/deployment-architecture.md
+++ b/docs/deployment-architecture.md
@@ -222,6 +222,12 @@ comparable (~200 ms) from Singapore or Sydney and does not favour either host.
   setting them as service variables inlines the real values. The publishable key
   is public by design; the placeholder default exists so CI can build without
   secrets. **Production images must be built with the real publishable key.**
+- `NEXT_PUBLIC_MAX_UPLOAD_MB` is also a build-time public variable (Docker
+  `ARG`/`ENV` before `npm run build`). When operators lower server-side
+  `MAX_UPLOAD_MB`, mirror the same value in `NEXT_PUBLIC_MAX_UPLOAD_MB` before
+  building the production image so the browser precheck rejects over-limit
+  files without a full transfer. Runtime-only Railway variables are not enough
+  for this value because Next inlines `NEXT_PUBLIC_*` at build time.
 - Runtime is a non-root `node` user, prod-only `node_modules`, direct
   `next start -H 0.0.0.0 -p $PORT` (Railway injects `$PORT`; the local
   port-picker script is deliberately bypassed), and a `HEALTHCHECK` against
diff --git a/tests/upload-size-precheck.dom.test.tsx b/tests/upload-size-precheck.dom.test.tsx
index 7ef85ec6bd..1eeaffa337 100644
--- a/tests/upload-size-precheck.dom.test.tsx
+++ b/tests/upload-size-precheck.dom.test.tsx
@@ -77,6 +77,9 @@ beforeEach(() => {
   FakeXhr.lastResponse = JSON.stringify({ document: { id: "doc-1" }, job: { id: "job-1" } });
   vi.stubGlobal("XMLHttpRequest", FakeXhr);
   vi.unstubAllEnvs();
+  // Pin empty so default-limit assertions stay deterministic when the shell/CI
+  // already exports NEXT_PUBLIC_MAX_UPLOAD_MB (vi.unstubAllEnvs restores it).
+  vi.stubEnv("NEXT_PUBLIC_MAX_UPLOAD_MB", "");
 });
 
 afterEach(() => {