From e22b336e8c78dd4c9f6f52e79272062dd6f68549 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 20 Jul 2026 07:46:38 +0000
Subject: [PATCH 01/15] Refactor clearance terminology to document approval
 across services and UI components

---
 .../booking-lifecycle-notifier.service.ts     |  8 +++----
 .../contracts/contract-clearance.service.ts   |  2 +-
 .../detail/ClearanceReviewSection.tsx         | 10 +++++----
 .../ContractClearanceReviewSection.tsx        |  6 +++---
 .../trainBuilder/BuildTrainModal.tsx          |  3 ++-
 .../trainBuilder/EditTrainDetailsModal.tsx    |  3 ++-
 .../src/hooks/contracts/useContracts.ts       |  8 ++++---
 .../src/hooks/useImportTrainNumberOptions.ts  | 21 ++++++++++++-------
 .../bookings/DocumentClearanceListPage.tsx    |  2 +-
 .../contracts/ContractClearanceListPage.tsx   |  4 ++--
 10 files changed, 40 insertions(+), 27 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.ts
index 1cef9528c..3809dc086 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.ts
@@ -157,13 +157,13 @@ export class BookingLifecycleNotifierService {
     });
   }
 
-  /** Clearance finalized → customer can proceed to request operation. */
+  /** Document approval finalized → customer can proceed to request operation. */
   clearanceReady(b: Booking): void {
     const msg =
-      `Clearance for booking ${b.reference} is complete. ` +
+      `Document approval for booking ${b.reference} is finalized. ` +
       `You can now proceed to request operation from the portal.`;
-    void this.notifyContact(b, msg, 'CLEARANCE READY');
-    this.inApp(b, 'Clearance complete', msg, {
+    void this.notifyContact(b, msg, 'DOCUMENT APPROVAL FINALIZED');
+    this.inApp(b, 'Document approval finalized', msg, {
       type: NotificationType.CLEARANCE_DECISION,
     });
   }
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts
index d3bbaf098..4b179814c 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts
@@ -446,7 +446,7 @@ export class ContractClearanceService {
     const allowed = ['CLEARANCE_UNDER_REVIEW', 'AWAITING_CLEARANCE_DOCUMENTS'];
     if (!allowed.includes(contract.status)) {
       throw new ConflictException(
-        `Cannot finalize clearance on status "${contract.status}".`,
+        `Cannot finalize document approval on status "${contract.status}".`,
       );
     }
   }
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/ClearanceReviewSection.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/ClearanceReviewSection.tsx
index 3dcf1ea9e..501e074e2 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/ClearanceReviewSection.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/ClearanceReviewSection.tsx
@@ -135,12 +135,14 @@ export function ClearanceReviewSection({
   const finalizeMutation = useMutation({
     mutationFn: () => bookingsService.finalizeClearance(bookingId),
     onSuccess: () => {
-      toast.success("Clearance finalized");
+      toast.success("Document approval finalized");
       refresh();
     },
     onError: (e) =>
       toast.error(
-        e instanceof Error ? e.message : "Could not finalize clearance",
+        e instanceof Error
+          ? e.message
+          : "Could not finalize document approval",
       ),
   });
 
@@ -366,7 +368,7 @@ export function ClearanceReviewSection({
         <Alert color="red" radius="md" icon={<AlertCircle size={16} />}>
           {finalizeMutation.error instanceof Error
             ? finalizeMutation.error.message
-            : "Could not finalize clearance."}
+            : "Could not finalize document approval."}
         </Alert>
       )}
 
@@ -445,7 +447,7 @@ export function ClearanceReviewSection({
               loading={finalizeMutation.isPending}
               onClick={() => finalizeMutation.mutate()}
             >
-              Finalize clearance
+              Finalize document approval
             </Button>
           </Group>
         </Paper>
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/ContractClearanceReviewSection.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/ContractClearanceReviewSection.tsx
index c85dc0b07..c7d668ade 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/ContractClearanceReviewSection.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/ContractClearanceReviewSection.tsx
@@ -68,7 +68,7 @@ export interface ContractClearanceReviewSectionProps {
   queriesLocked?: boolean;
   /**
    * ONE_TIME customs contracts use the phased milestone workflow. Hides the
-   * legacy "Finalize clearance" shortcut; booking readiness follows delivery
+   * legacy "Finalize document approval" shortcut; booking readiness follows delivery
    * order (import) or export release.
    */
   phasedCustoms?: boolean;
@@ -393,7 +393,7 @@ export function ContractClearanceReviewSection({
         <Alert color="red" radius="md" icon={<AlertCircle size={16} />}>
           {finalizeClearance.error instanceof Error
             ? finalizeClearance.error.message
-            : "Could not finalize clearance."}
+            : "Could not finalize document approval."}
         </Alert>
       )}
 
@@ -482,7 +482,7 @@ export function ContractClearanceReviewSection({
                 })
               }
             >
-              Finalize clearance
+              Finalize document approval
             </Button>
           </Group>
         </Paper>
diff --git a/apps/edr-freight-web/backoffice/src/components/trainBuilder/BuildTrainModal.tsx b/apps/edr-freight-web/backoffice/src/components/trainBuilder/BuildTrainModal.tsx
index 05b4bd546..925ff528d 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainBuilder/BuildTrainModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainBuilder/BuildTrainModal.tsx
@@ -160,7 +160,8 @@ export default function BuildTrainModal({ opened, onClose, onBuilt }: BuildTrain
             onChange={(value) => setImportTrainNumber(value ?? "")}
             searchable
             clearable
-            nothingFoundMessage="No free run numbers — add more in Dropdown Settings"
+            nothingFoundMessage={importNumbers.emptyMessage}
+            error={importNumbers.settingMissing ? importNumbers.emptyMessage : undefined}
           />
         </Group>
         <Select
diff --git a/apps/edr-freight-web/backoffice/src/components/trainBuilder/EditTrainDetailsModal.tsx b/apps/edr-freight-web/backoffice/src/components/trainBuilder/EditTrainDetailsModal.tsx
index 8eb64d3ef..cd65a568a 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainBuilder/EditTrainDetailsModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainBuilder/EditTrainDetailsModal.tsx
@@ -105,7 +105,8 @@ const EditTrainDetailsModal = ({ train, onClose }: EditTrainDetailsModalProps) =
             }}
             searchable
             clearable
-            nothingFoundMessage="No free run numbers — add more in Dropdown Settings"
+            nothingFoundMessage={importNumbers.emptyMessage}
+            error={importNumbers.settingMissing ? importNumbers.emptyMessage : undefined}
             radius="md"
           />
           <TextInput
diff --git a/apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts b/apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts
index 572ad6f8e..306d92536 100644
--- a/apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts
+++ b/apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts
@@ -348,14 +348,16 @@ export function useContractClearanceMutations(
     onSuccess: () => {
       toast.success(
         selfClear
-          ? "Clearance approved — customer can now book"
-          : "Clearance finalized — ready for booking",
+          ? "Document approval finalized — customer can now book"
+          : "Document approval finalized — ready for booking",
       );
       refresh();
     },
     onError: (e) =>
       toast.error(
-        e instanceof Error ? e.message : "Could not finalize clearance",
+        e instanceof Error
+          ? e.message
+          : "Could not finalize document approval",
       ),
   });
 
diff --git a/apps/edr-freight-web/backoffice/src/hooks/useImportTrainNumberOptions.ts b/apps/edr-freight-web/backoffice/src/hooks/useImportTrainNumberOptions.ts
index a26e127f3..d2cf2710d 100644
--- a/apps/edr-freight-web/backoffice/src/hooks/useImportTrainNumberOptions.ts
+++ b/apps/edr-freight-web/backoffice/src/hooks/useImportTrainNumberOptions.ts
@@ -1,7 +1,6 @@
 import { useQuery } from "@tanstack/react-query";
 import { useMemo } from "react";
 
-import { IMPORT_TRAIN_OPTIONS } from "@/constants/trainRuns";
 import { api } from "@/services/api";
 
 /** Dropdown-settings code holding the admin-managed IMPORT run numbers. */
@@ -14,10 +13,11 @@ export interface ImportTrainNumberOption {
 }
 
 /**
- * Selectable IMPORT run numbers for the Train Builder, sourced from the
- * admin-managed `import_train_numbers` dropdown setting (admins add new runs
- * from the Dropdown Settings editor). Falls back to the legacy hardcoded run
- * list while the setting is missing or has no options.
+ * Selectable IMPORT run numbers for the Train Builder, sourced solely from the
+ * admin-managed `import_train_numbers` dropdown setting — admins add and remove
+ * runs from /dashboard/dropdown-settings and the pickers follow. There is no
+ * hardcoded fallback on purpose: a missing setting must be visible (see
+ * `settingMissing`) rather than masked by stale defaults.
  *
  * Numbers already claimed by an existing train are kept in the list but
  * disabled and tagged "in use". Pass `currentNumber` when editing a train so
@@ -37,14 +37,13 @@ export function useImportTrainNumberOptions(currentNumber?: string | null) {
   );
 
   const options = useMemo<ImportTrainNumberOption[]>(() => {
-    const configured = [...(settingQuery.data?.children ?? [])]
+    const base = [...(settingQuery.data?.children ?? [])]
       .filter((option) => !option.disabled)
       .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
       .map((option) => ({
         value: option.value,
         label: option.label || option.value,
       }));
-    const base = configured.length ? configured : IMPORT_TRAIN_OPTIONS;
 
     const used = new Set(usedQuery.data?.importTrainNumbers ?? []);
     if (currentNumber) used.delete(currentNumber);
@@ -60,8 +59,16 @@ export function useImportTrainNumberOptions(currentNumber?: string | null) {
     return items;
   }, [settingQuery.data, usedQuery.data, currentNumber]);
 
+  const settingMissing = settingQuery.isError;
+
   return {
     options,
     isLoading: settingQuery.isLoading || usedQuery.isLoading,
+    /** True when the dropdown setting is absent — surfaced instead of silently
+     * falling back, so a broken config is visible rather than looking normal. */
+    settingMissing,
+    emptyMessage: settingMissing
+      ? `Dropdown setting "${IMPORT_TRAIN_NUMBERS_CODE}" is missing — create it in Dropdown Settings`
+      : "No free run numbers — add more in Dropdown Settings",
   };
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceListPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceListPage.tsx
index 542852a5f..34e659177 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceListPage.tsx
@@ -325,7 +325,7 @@ export default function DocumentClearanceListPage({
           subtitle={
             opsMode
               ? "Review the customer's own clearance documents per shipment booking, raise queries, and finalize."
-              : "Review customer documents, raise queries, and finalize clearance for each booking."
+              : "Review customer documents, raise queries, and finalize document approval for each booking."
           }
           meta={statusBadge}
           action={
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx
index 9cc9919e3..328736f3d 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx
@@ -256,7 +256,7 @@ function StatusBadge({ row }: { row: ClearanceRow }) {
   if (row.ready) {
     return (
       <Tooltip
-        label="Clearance finalized — the customer creates the booking in the portal"
+        label="Document approval finalized — the customer creates the booking in the portal"
         withArrow
       >
         <Badge
@@ -266,7 +266,7 @@ function StatusBadge({ row }: { row: ClearanceRow }) {
           radius="sm"
           leftSection={<PackageCheck size={12} />}
         >
-          Clearance finalized
+          Documents approved
         </Badge>
       </Tooltip>
     );

From c1c362ab9d93398bd49d279a7f96c6a4482eb226 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 20 Jul 2026 08:03:16 +0000
Subject: [PATCH 02/15] fix(mile): only send bookings that bought EDR haulage
 to the mile queues
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The rule that a customer's own truck and an EDR road leg are alternatives
existed on the truck side only (CustomerTruckService.assertSelfHaulPaid).
LastMileService had no counterpart: create checked payment and nothing else,
so any paid booking could be accepted into the queue. A booking took a
customer truck at 06:42 and an EDR last-mile leg with a real EDR truck at
06:47, neither side aware of the other, on a contract that had chosen no
road legs at all.

The road legs are chosen on the contract and copied onto the booking, and
the pickup/delivery address is the only per-booking record of that choice.
service_types cannot serve: every type ships with includes_first_mile and
includes_last_mile set to true, so reading them would mean no booking could
ever self-haul. That same always-true flag had already killed the first-mile
guard, whose `address || serviceType.includesFirstMile` admitted every paid
export booking.

One shared rule now answers it for both sides, so the two halves cannot
drift apart again: last-mile create rejects a booking that chose no road
legs and one already carrying a customer truck; first-mile no longer honours
the service-type flag; the customer-truck guard reads the same helper.

Existing legs are untouched — the guards are on creation, so the one booking
already carrying both needs a human to reconcile it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../src/common/mile-haulage.util.spec.ts      | 52 ++++++++++
 .../src/common/mile-haulage.util.ts           | 49 +++++++++
 .../bookings/customer-truck.service.ts        | 21 ++--
 .../modules/first-mile/first-mile.service.ts  |  8 +-
 .../modules/last-mile/last-mile.guard.spec.ts | 99 +++++++++++++++++++
 .../modules/last-mile/last-mile.service.ts    | 48 +++++++++
 6 files changed, 262 insertions(+), 15 deletions(-)
 create mode 100644 apps/edr-freight-api/src/common/mile-haulage.util.spec.ts
 create mode 100644 apps/edr-freight-api/src/common/mile-haulage.util.ts
 create mode 100644 apps/edr-freight-api/src/modules/last-mile/last-mile.guard.spec.ts

diff --git a/apps/edr-freight-api/src/common/mile-haulage.util.spec.ts b/apps/edr-freight-api/src/common/mile-haulage.util.spec.ts
new file mode 100644
index 000000000..8c3310321
--- /dev/null
+++ b/apps/edr-freight-api/src/common/mile-haulage.util.spec.ts
@@ -0,0 +1,52 @@
+import { usesEdrMileService } from './mile-haulage.util';
+
+/**
+ * The road legs are chosen on the contract and copied onto the booking. EDR
+ * haulage and a customer's own truck are alternatives, so this one answer gates
+ * both sides — the customer-truck guard and the mile-queue guard.
+ */
+describe('usesEdrMileService', () => {
+  const booking = (over: Partial<Parameters<typeof usesEdrMileService>[0]> = {}) => ({
+    tradeDirection: 'IMPORT',
+    firstMile: null,
+    lastMile: null,
+    ...over,
+  });
+
+  it('an import that chose delivery uses EDR haulage', () => {
+    expect(usesEdrMileService(booking({ lastMile: 'Bole, Addis Ababa' }))).toBe(true);
+  });
+
+  it('an import that chose nothing does not', () => {
+    expect(usesEdrMileService(booking())).toBe(false);
+  });
+
+  it('ignores the pickup address on an import — collection is the export leg', () => {
+    expect(usesEdrMileService(booking({ firstMile: 'Modjo' }))).toBe(false);
+  });
+
+  it('an export that chose collection uses EDR haulage', () => {
+    expect(
+      usesEdrMileService(booking({ tradeDirection: 'EXPORT', firstMile: 'Modjo' })),
+    ).toBe(true);
+  });
+
+  it('ignores the delivery address on an export — delivery is the import leg', () => {
+    expect(
+      usesEdrMileService(booking({ tradeDirection: 'EXPORT', lastMile: 'Djibouti' })),
+    ).toBe(false);
+  });
+
+  it('a domestic booking counts either leg', () => {
+    expect(
+      usesEdrMileService(booking({ tradeDirection: 'DOMESTIC', firstMile: 'Adama' })),
+    ).toBe(true);
+    expect(
+      usesEdrMileService(booking({ tradeDirection: 'DOMESTIC', lastMile: 'Dire Dawa' })),
+    ).toBe(true);
+  });
+
+  it('treats a whitespace-only address as no choice', () => {
+    expect(usesEdrMileService(booking({ lastMile: '   ' }))).toBe(false);
+  });
+});
diff --git a/apps/edr-freight-api/src/common/mile-haulage.util.ts b/apps/edr-freight-api/src/common/mile-haulage.util.ts
new file mode 100644
index 000000000..1ca83d06e
--- /dev/null
+++ b/apps/edr-freight-api/src/common/mile-haulage.util.ts
@@ -0,0 +1,49 @@
+/** The booking fields that decide who hauls the road legs. */
+export interface MileHaulageRow {
+  tradeDirection: string | null;
+  /** `first_mile_pickup_address` — set when the customer asked EDR to collect. */
+  firstMile: string | null;
+  /** `last_mile_delivery_address` — set when the customer asked EDR to deliver. */
+  lastMile: string | null;
+}
+
+/**
+ * Whether the customer bought the EDR road leg that matters for their direction:
+ * delivery at the end of an import, collection at the start of an export. A
+ * DOMESTIC booking can use either, so either one counts.
+ *
+ * The address is the signal because it is the only per-booking record of the
+ * choice. `service_types.includes_first_mile` / `includes_last_mile` cannot be
+ * used — every service type ships with both set to true, so reading them would
+ * mean every booking uses EDR haulage and none could ever self-haul.
+ */
+export function usesEdrMileService(booking: MileHaulageRow): boolean {
+  const hasFirstMile = Boolean(booking.firstMile?.trim());
+  const hasLastMile = Boolean(booking.lastMile?.trim());
+  switch (booking.tradeDirection) {
+    case 'IMPORT':
+      return hasLastMile;
+    case 'EXPORT':
+      return hasFirstMile;
+    default:
+      return hasFirstMile || hasLastMile;
+  }
+}
+
+/**
+ * EDR haulage and a customer's own truck are alternatives, never both. Whichever
+ * side is being set up, it has to reject the other — a guard on only one side
+ * lets the two paths open on the same booking, each unaware of the other.
+ */
+export const SELF_HAUL_CONFLICT_MESSAGE =
+  'This booking is delivered by the customer’s own truck — an EDR mile leg cannot also be assigned.';
+
+export const EDR_HAULAGE_CONFLICT_MESSAGE =
+  'Customer truck assignment is only allowed when first/last mile delivery is not selected';
+
+/**
+ * The road legs are chosen on the contract. A booking whose contract bought
+ * neither has no business in the first/last-mile queues at all.
+ */
+export const NO_MILE_SERVICE_MESSAGE =
+  'This booking did not select first/last mile delivery on its contract, so it cannot be assigned an EDR mile leg.';
diff --git a/apps/edr-freight-api/src/modules/bookings/customer-truck.service.ts b/apps/edr-freight-api/src/modules/bookings/customer-truck.service.ts
index f366faa96..7b0145db2 100644
--- a/apps/edr-freight-api/src/modules/bookings/customer-truck.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/customer-truck.service.ts
@@ -12,6 +12,10 @@ import { AddCustomerTruckDto } from './dto/add-customer-truck.dto';
 import { DepartCustomerTruckDto } from './dto/depart-customer-truck.dto';
 import { CustomerTruckAssignment } from './entities/customer-truck-assignment.entity';
 import { CustomerTruckContainer } from './entities/customer-truck-container.entity';
+import {
+  EDR_HAULAGE_CONFLICT_MESSAGE,
+  usesEdrMileService,
+} from '../../common/mile-haulage.util';
 import { CustomerTruckAssignmentsRepository } from './customer-truck-assignments.repository';
 import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
 import { NotificationsService } from '../notifications/notifications.service';
@@ -534,18 +538,11 @@ export class CustomerTruckService {
   }
 
   private assertSelfHaulPaid(booking: BookingGuardRow): void {
-    const hasFirstMile = Boolean(booking.firstMile?.trim());
-    const hasLastMile = Boolean(booking.lastMile?.trim());
-    const usesMileService =
-      booking.tradeDirection === 'IMPORT'
-        ? hasLastMile
-        : booking.tradeDirection === 'EXPORT'
-          ? hasFirstMile
-          : hasFirstMile || hasLastMile;
-    if (usesMileService) {
-      throw new BadRequestException(
-        'Customer truck assignment is only allowed when first/last mile delivery is not selected',
-      );
+    // Shared with the EDR side (LastMileService.assertNoCustomerTruck) so the two
+    // halves of this rule cannot drift apart — they did, and a booking ended up
+    // with a customer truck and an EDR leg at once.
+    if (usesEdrMileService(booking)) {
+      throw new BadRequestException(EDR_HAULAGE_CONFLICT_MESSAGE);
     }
     if (booking.paymentStatus !== 'PAID') {
       throw new BadRequestException(
diff --git a/apps/edr-freight-api/src/modules/first-mile/first-mile.service.ts b/apps/edr-freight-api/src/modules/first-mile/first-mile.service.ts
index 00dbb80cc..0143f0796 100644
--- a/apps/edr-freight-api/src/modules/first-mile/first-mile.service.ts
+++ b/apps/edr-freight-api/src/modules/first-mile/first-mile.service.ts
@@ -333,10 +333,12 @@ export class FirstMileService {
     firstMilePickupAddress?: string | null;
     serviceType?: { includesFirstMile?: boolean | null } | null;
   }): boolean {
+    // The pickup address is the only record of what the contract chose.
+    // `serviceType.includesFirstMile` used to satisfy this too, but every
+    // service type ships with it set to true, so the OR made the address check
+    // dead and admitted every paid export booking into the queue.
     return Boolean(
-      booking.tradeDirection === 'EXPORT' &&
-      (booking.firstMilePickupAddress?.trim() ||
-        booking.serviceType?.includesFirstMile),
+      booking.tradeDirection === 'EXPORT' && booking.firstMilePickupAddress?.trim(),
     );
   }
 
diff --git a/apps/edr-freight-api/src/modules/last-mile/last-mile.guard.spec.ts b/apps/edr-freight-api/src/modules/last-mile/last-mile.guard.spec.ts
new file mode 100644
index 000000000..232f59d50
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/last-mile/last-mile.guard.spec.ts
@@ -0,0 +1,99 @@
+import { BadRequestException } from '@nestjs/common';
+import type { DataSource } from 'typeorm';
+
+import { LastMileService } from './last-mile.service';
+
+/**
+ * A booking reaches the last-mile queue only if its contract bought EDR
+ * delivery, and never if the customer is hauling it themselves. Creation used
+ * to check payment alone, so any paid booking could be accepted — which put a
+ * self-haul booking and an EDR leg on the same shipment at once.
+ */
+type BookingRow = { tradeDirection: string; firstMile: string | null; lastMile: string | null };
+
+function makeService(opts: { booking?: BookingRow; hasCustomerTruck?: boolean }) {
+  const booking = opts.booking ?? {
+    tradeDirection: 'IMPORT',
+    firstMile: null,
+    lastMile: 'Bole, Addis Ababa',
+  };
+
+  const query = jest.fn((sql: string) => {
+    if (sql.includes('customer_truck_assignments')) {
+      return Promise.resolve(opts.hasCustomerTruck ? [{ '?column?': 1 }] : []);
+    }
+    if (sql.includes('FROM freight.bookings')) {
+      return Promise.resolve([booking]);
+    }
+    return Promise.resolve([]);
+  });
+
+  const lastMileRepository = {
+    findAll: jest.fn().mockResolvedValue([]),
+    create: jest.fn((row: unknown) => Promise.resolve({ id: 'lm-1', ...(row as object) })),
+  };
+
+  const service = new LastMileService(
+    lastMileRepository as never,
+    {} as never, // bookingsRepository
+    { setAvailability: jest.fn() } as never, // vehiclesService
+    {} as never, // driversService
+    {} as never, // smsClient
+    { query } as unknown as DataSource,
+    { record: jest.fn() } as never, // history
+    {} as never, // billing
+    {} as never, // filesService
+  );
+
+  return { service, lastMileRepository, query };
+}
+
+describe('LastMileService.create — haulage guard', () => {
+  it('accepts a booking whose contract chose EDR delivery', async () => {
+    const { service, lastMileRepository } = makeService({});
+
+    await service.create({ bookingId: 'b-1', advancedPayment: 0 } as never);
+
+    expect(lastMileRepository.create).toHaveBeenCalled();
+  });
+
+  it('rejects a booking that chose no road legs on its contract', async () => {
+    const { service, lastMileRepository } = makeService({
+      booking: { tradeDirection: 'IMPORT', firstMile: null, lastMile: null },
+    });
+
+    await expect(
+      service.create({ bookingId: 'b-1', advancedPayment: 0 } as never),
+    ).rejects.toBeInstanceOf(BadRequestException);
+    expect(lastMileRepository.create).not.toHaveBeenCalled();
+  });
+
+  it('rejects a booking already hauled by the customer’s own truck', async () => {
+    const { service, lastMileRepository } = makeService({ hasCustomerTruck: true });
+
+    await expect(
+      service.create({ bookingId: 'b-1', advancedPayment: 0 } as never),
+    ).rejects.toBeInstanceOf(BadRequestException);
+    expect(lastMileRepository.create).not.toHaveBeenCalled();
+  });
+
+  it('rejects an import that only chose collection — that is the export leg', async () => {
+    const { service } = makeService({
+      booking: { tradeDirection: 'IMPORT', firstMile: 'Modjo', lastMile: null },
+    });
+
+    await expect(
+      service.create({ bookingId: 'b-1', advancedPayment: 0 } as never),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('returns the existing leg without re-checking, so the queue stays idempotent', async () => {
+    const { service, lastMileRepository } = makeService({ hasCustomerTruck: true });
+    lastMileRepository.findAll.mockResolvedValue([{ id: 'lm-existing' }]);
+
+    const result = await service.create({ bookingId: 'b-1', advancedPayment: 0 } as never);
+
+    expect(result).toEqual({ id: 'lm-existing' });
+    expect(lastMileRepository.create).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts b/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
index 1ee9d7191..aa293759c 100644
--- a/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
+++ b/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
@@ -7,6 +7,11 @@ import {
 } from '@nestjs/common';
 import { DataSource, FindOptionsWhere, In, IsNull, Not } from 'typeorm';
 
+import {
+  NO_MILE_SERVICE_MESSAGE,
+  SELF_HAUL_CONFLICT_MESSAGE,
+  usesEdrMileService,
+} from '../../common/mile-haulage.util';
 import { BookingsRepository } from '../bookings/bookings.repository';
 import { DriversService } from '../drivers/drivers.service';
 import { SmsClientService } from '../notifications/sms-client.service';
@@ -126,6 +131,47 @@ export class LastMileService {
     }
   }
 
+  /**
+   * Only a booking that actually bought EDR delivery belongs in the last-mile
+   * queue, and a booking hauled by the customer's own truck must never also get
+   * an EDR leg.
+   *
+   * Both halves were missing: creation checked payment alone, so any paid
+   * booking could be accepted into the queue — including one whose contract
+   * chose no road legs at all, and one already carrying a customer truck. The
+   * mirror rule existed on the truck side only
+   * (CustomerTruckService.assertSelfHaulPaid), so whichever side acted second
+   * silently opened a competing delivery on the same booking.
+   */
+  private async assertEdrHaulsThisBooking(bookingId?: string | null): Promise<void> {
+    if (!bookingId) return;
+
+    const [booking] = await this.dataSource.query(
+      `SELECT trade_direction           AS "tradeDirection",
+              first_mile_pickup_address AS "firstMile",
+              last_mile_delivery_address AS "lastMile"
+         FROM freight.bookings
+        WHERE id = $1 AND deleted_at IS NULL`,
+      [bookingId],
+    );
+    // The road legs are chosen on the contract and copied onto the booking, so
+    // the booking's own addresses answer this without a join.
+    if (booking && !usesEdrMileService(booking)) {
+      throw new BadRequestException(NO_MILE_SERVICE_MESSAGE);
+    }
+
+    const [truck] = await this.dataSource.query(
+      `SELECT 1
+         FROM freight.customer_truck_assignments
+        WHERE booking_id = $1 AND deleted_at IS NULL
+        LIMIT 1`,
+      [bookingId],
+    );
+    if (truck) {
+      throw new BadRequestException(SELF_HAUL_CONFLICT_MESSAGE);
+    }
+  }
+
   async acceptBooking(bookingReference: string): Promise<LastMile | null> {
     const booking = await this.bookingsRepository.findByReference(bookingReference);
 
@@ -352,6 +398,8 @@ export class LastMileService {
       return existing;
     }
 
+    await this.assertEdrHaulsThisBooking(dto.bookingId);
+
     const record = await this.lastMileRepository.create({
       bookingId: dto.bookingId,
       status: dto.status ?? 'READY_TO_TRANSIT',

From eb532399d9ad9ce7d8cb19076de589a9eefb134c Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 20 Jul 2026 10:52:20 +0000
Subject: [PATCH 03/15] changes

---
 .../modules/contracts/contracts.service.ts    | 13 ++++--------
 .../train-scheduling/booking-batch.service.ts | 17 +++++++++-------
 .../train-scheduling.service.ts               | 14 +++++++++++--
 .../TrainScheduleV2ListPage.tsx               |  6 ++++--
 .../components/DocumentsTab.tsx               | 20 +++++++++++++++++--
 .../pages/bookings/resubmit/resubmitDocs.ts   |  8 ++++++++
 .../pages/contracts/ContractDetailPage.tsx    |  9 ++++++++-
 7 files changed, 64 insertions(+), 23 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/contracts/contracts.service.ts b/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
index 224745cc4..c98e24b19 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
@@ -374,23 +374,18 @@ export class ContractsService {
     if (companyProfileId) {
       // Business-license files are FileRecords (resource "company_profiles");
       // carry the live ones by reference. Staged/pending uploads are excluded by
-      // code. Codes are slugged from each document name so they group under
-      // "Profile documents" on the contract detail page.
+      // code. The `business_license` prefix is preserved so the portal groups
+      // them under "Business license" instead of the clearance catch-all — the
+      // index suffix keeps multiple licences distinct.
       const records = await this.filesService.findByResource(
         companyProfileId,
         'company_profiles',
       );
-      const slug = (name: string) =>
-        name
-          .toLowerCase()
-          .replace(/\.[a-z0-9]+$/, '')
-          .replace(/[^a-z0-9]+/g, '_')
-          .replace(/^_+|_+$/g, '') || 'profile_document';
 
       records
         .filter((r) => r.code === 'business_license')
         .forEach((r, i) => {
-          const code = `${slug(r.name)}_${i + 1}`;
+          const code = `business_license_${i + 1}`;
           if (existingCodes.has(code)) return;
           docs.push({
             code,
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts
index 4a836060e..415b5df97 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts
@@ -3444,19 +3444,22 @@ export class BookingBatchService implements OnModuleInit {
 
   /**
    * Physical wagons marshalled in the schedule's built train, or null when the
-   * schedule has no built train (or the consist is still empty) and the legacy
-   * locomotive-derived capacity must apply. This count is what caps a built
-   * train's bookings: 50 wagons coupled → 50 wagon slots, no more.
+   * schedule has NO built train and the legacy locomotive-derived capacity must
+   * apply. This count is what caps a built train's bookings: 50 wagons coupled
+   * → 50 wagon slots, no more.
+   *
+   * A built train with an EMPTY consist returns 0, NOT null: zero coupled
+   * wagons means zero capacity. Folding that case into null used to hand an
+   * un-consisted train the abstract locomotive budget, so an empty train
+   * advertised its full maxWagons as free space and accepted bookings the
+   * allocator could never place.
    */
   private async builtTrainWagonCount(
     schedule: TrainSchedule,
   ): Promise<number | null> {
     const trainId = schedule.trainSet?.train?.id;
     if (!trainId) return null;
-    const count = await this.dataSource
-      .getRepository(Wagon)
-      .count({ where: { trainId } });
-    return count > 0 ? count : null;
+    return this.dataSource.getRepository(Wagon).count({ where: { trainId } });
   }
 
   /**
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.service.ts
index cccf9e57e..e61fe52ac 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.service.ts
@@ -7090,9 +7090,19 @@ export class TrainSchedulingService {
 
     await this.dataSource.transaction(async (manager) => {
       await manager.getRepository(TrainSetWagon).delete(trainSetWagonId);
+      // Recount from the slot rows rather than decrementing the cached counter.
+      // A blind `wagonCount - 1` desyncs the moment two removals race or the
+      // in-memory schedule graph is stale, and the counter is what the schedule
+      // capacity math reads.
+      const remaining = await manager.getRepository(TrainSetWagon).find({
+        where: { trainSetId: schedule.trainSetId },
+        select: { id: true, lengthMeters: true },
+      });
       await manager.getRepository(TrainSet).update(schedule.trainSetId, {
-        wagonCount: Math.max(0, (schedule.trainSet?.wagonCount ?? 0) - 1),
-        totalLengthMeters: Math.max(0, (schedule.trainSet?.totalLengthMeters ?? 0) - (wagon.lengthMeters ?? 0)),
+        wagonCount: remaining.length,
+        totalLengthMeters: roundTons(
+          remaining.reduce((sum, w) => sum + (Number(w.lengthMeters) || 0), 0),
+        ),
       });
     });
 
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
index f40bd9526..aae182103 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
@@ -400,7 +400,9 @@ export default function TrainScheduleV2ListPage() {
         cell: ({ row }) => (
           <Group gap={6} wrap="nowrap">
             <MetricChip value={row.original.bookingsCount} label="bkg" />
-            <MetricChip value={row.original.wagonCount} label="wgn" />
+            {/* Wagon SLOTS this schedule's bookings occupy — not the coupled
+                consist. A built train shows 0 here until bookings are allocated. */}
+            <MetricChip value={row.original.wagonCount} label="wgn used" />
             <MetricChip value={`${row.original.totalWeightTons}T`} label="" subtle />
           </Group>
         ),
@@ -950,7 +952,7 @@ function ScheduleCard({
           </Group>
           <Group gap={6} wrap="nowrap">
             <MetricChip value={schedule.bookingsCount} label="bkg" />
-            <MetricChip value={schedule.wagonCount} label="wgn" />
+            <MetricChip value={schedule.wagonCount} label="wgn used" />
             <MetricChip value={`${schedule.totalWeightTons}T`} label="" subtle />
           </Group>
         </Group>
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/DocumentsTab.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/DocumentsTab.tsx
index 983411e89..8934a0a60 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/DocumentsTab.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/DocumentsTab.tsx
@@ -158,7 +158,14 @@ const BUSINESS_LICENSE_DOC_CODES = new Set([
   "business_license",
   "commercial_license",
   "investment_license",
+  "trade_license",
 ]);
+
+// Licences carried from the company profile are suffixed per file
+// (`business_license_1`), so match on the stripped base code too.
+const isBusinessLicenseCode = (code: string): boolean =>
+  BUSINESS_LICENSE_DOC_CODES.has(code) ||
+  BUSINESS_LICENSE_DOC_CODES.has(code.replace(/_\d+$/, ""));
 const PROFILE_DOC_CODES = new Set([
   "tin_certificate",
   "national_id",
@@ -183,6 +190,15 @@ const KNOWN_FILE_LABELS: Record<string, string> = {
 
 function fileLabel(f: AnyFile) {
   if (KNOWN_FILE_LABELS[f.code]) return KNOWN_FILE_LABELS[f.code];
+  // Profile documents carried onto the contract are suffixed per file
+  // (`business_license_2`) — label them from the base code, numbered.
+  const base = f.code.replace(/_\d+$/, "");
+  if (KNOWN_FILE_LABELS[base]) {
+    const n = f.code.slice(base.length + 1);
+    return n && n !== "1"
+      ? `${KNOWN_FILE_LABELS[base]} ${n}`
+      : KNOWN_FILE_LABELS[base];
+  }
   // Ad-hoc uploads carry a generated code (custom_<ts>_<i>) — use the filename.
   if (f.code.startsWith("custom_")) return f.name;
   return f.code
@@ -245,7 +261,7 @@ export function DocumentsTab({ booking }: { booking: Freight.IBooking }) {
   const contractFiles = (contract?.files ?? []) as AnyFile[];
   const contractPdf = contractFiles.find((f) => f.code === "contract");
   const licenseFiles = contractFiles.filter((f) =>
-    BUSINESS_LICENSE_DOC_CODES.has(f.code),
+    isBusinessLicenseCode(f.code),
   );
   const profileFiles = contractFiles.filter((f) => PROFILE_DOC_CODES.has(f.code));
 
@@ -428,7 +444,7 @@ export function DocumentsTab({ booking }: { booking: Freight.IBooking }) {
                   title={fileLabel(f)}
                   meta={
                     PROFILE_DOC_CODES.has(f.code) ||
-                    BUSINESS_LICENSE_DOC_CODES.has(f.code)
+                    isBusinessLicenseCode(f.code)
                       ? "From your company profile"
                       : f.name
                   }
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/resubmit/resubmitDocs.ts b/apps/edr-freight-web/portal/src/pages/bookings/resubmit/resubmitDocs.ts
index 0a2f1a30f..fb36c3fd2 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/resubmit/resubmitDocs.ts
+++ b/apps/edr-freight-web/portal/src/pages/bookings/resubmit/resubmitDocs.ts
@@ -26,6 +26,14 @@ const LABEL_BY_CODE = new Map<string, string>([
 export function labelForDocCode(code: string): string {
   const known = LABEL_BY_CODE.get(code);
   if (known) return known;
+  // Profile documents carried onto a contract are suffixed per file
+  // ("business_license_2") — label from the base code, numbered past the first.
+  const base = code.replace(/_\d+$/, "");
+  const baseLabel = LABEL_BY_CODE.get(base);
+  if (baseLabel) {
+    const n = code.slice(base.length + 1);
+    return n && n !== "1" ? `${baseLabel} ${n}` : baseLabel;
+  }
   return code
     .replace(/^custom_\d+_\d+$/, "Additional document")
     .replace(/[_-]+/g, " ")
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/ContractDetailPage.tsx b/apps/edr-freight-web/portal/src/pages/contracts/ContractDetailPage.tsx
index f03f99b01..89870ee93 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/ContractDetailPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/ContractDetailPage.tsx
@@ -134,8 +134,15 @@ const BUSINESS_LICENSE_DOC_CODES = new Set([
   "business_license",
   "commercial_license",
   "investment_license",
+  "trade_license",
 ]);
 
+// Licences carried from the company profile are suffixed per file
+// (`business_license_1`), so match on the stripped base code too.
+const isBusinessLicenseCode = (code: string): boolean =>
+  BUSINESS_LICENSE_DOC_CODES.has(code) ||
+  BUSINESS_LICENSE_DOC_CODES.has(code.replace(/_\d+$/, ""));
+
 // Onboarding / company-profile document codes seeded in file-upload-settings.
 // These get attached to the contract at creation and belong under "Profile
 // documents" rather than the clearance set.
@@ -196,7 +203,7 @@ function groupContractDocuments(
     // The generated contract PDF lives in the contract list / home rows, not
     // here. Signature images are baked into that PDF — skip both.
     if (f.code === "contract" || f.code.startsWith("signature_")) continue;
-    else if (BUSINESS_LICENSE_DOC_CODES.has(f.code)) businessLicense.push(f);
+    else if (isBusinessLicenseCode(f.code)) businessLicense.push(f);
     else if (PROFILE_DOC_CODES.has(f.code)) profile.push(f);
     else if (includeClearance && isClearanceCode(f.code)) clearance.push(f);
     else other.push(f);

From 9fbe1c5236cd8a764fbf0599e28929ae16e3156c Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 18 Jul 2026 08:52:06 +0000
Subject: [PATCH 04/15] feat: setup attachment to the freight chat

---
 .../2320000000000-SupportChatAttachments.ts   |  50 +++
 .../src/modules/files/files.controller.ts     |  30 +-
 .../src/modules/files/files.repository.ts     |  17 +-
 .../src/modules/files/files.service.ts        |  47 ++-
 .../support-chat/attachment-upload.options.ts |  25 ++
 .../dto/list-messages-query.dto.ts            |  30 ++
 .../support-chat/dto/send-message.dto.ts      |  14 +-
 .../entities/support-message.entity.ts        |   8 +-
 .../modules/support-chat/message-cursor.ts    |  54 +++
 .../support-attachment.controller.ts          | 100 +++++
 .../support-chat-agent.controller.ts          |  63 ++-
 .../support-chat/support-chat.controller.ts   |  75 +++-
 .../support-chat/support-chat.module.ts       |  13 +-
 .../support-chat/support-chat.service.ts      | 278 +++++++++++--
 .../support-message.repository.ts             |  54 ++-
 .../features/support/AttachmentDraftBar.tsx   |  78 ++++
 .../features/support/MessageAttachments.tsx   | 122 ++++++
 .../src/features/support/supportApi.ts        |  57 ++-
 .../features/support/useAttachmentDraft.ts    | 130 ++++++
 .../support/useAttachmentObjectUrl.ts         |  80 ++++
 .../src/features/support/useSupport.ts        | 165 +++++++-
 .../src/features/support/useSupportSocket.ts  |  28 +-
 .../src/pages/support/SupportInboxPage.tsx    | 374 +++++++++++++++---
 .../features/support/AttachmentDraftBar.tsx   |  80 ++++
 .../features/support/MessageAttachments.tsx   | 123 ++++++
 .../src/features/support/SupportPanel.tsx     | 254 ++++++++++--
 .../src/features/support/SupportWidget.tsx    |  20 +-
 .../portal/src/features/support/supportApi.ts |  64 ++-
 .../features/support/useAttachmentDraft.ts    | 130 ++++++
 .../support/useAttachmentObjectUrl.ts         |  80 ++++
 .../portal/src/features/support/useSupport.ts | 104 ++++-
 .../src/features/support/useSupportSocket.ts  |  30 +-
 32 files changed, 2582 insertions(+), 195 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/2320000000000-SupportChatAttachments.ts
 create mode 100644 apps/edr-freight-api/src/modules/support-chat/attachment-upload.options.ts
 create mode 100644 apps/edr-freight-api/src/modules/support-chat/dto/list-messages-query.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/support-chat/message-cursor.ts
 create mode 100644 apps/edr-freight-api/src/modules/support-chat/support-attachment.controller.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/features/support/AttachmentDraftBar.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/features/support/MessageAttachments.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/features/support/useAttachmentDraft.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/features/support/useAttachmentObjectUrl.ts
 create mode 100644 apps/edr-freight-web/portal/src/features/support/AttachmentDraftBar.tsx
 create mode 100644 apps/edr-freight-web/portal/src/features/support/MessageAttachments.tsx
 create mode 100644 apps/edr-freight-web/portal/src/features/support/useAttachmentDraft.ts
 create mode 100644 apps/edr-freight-web/portal/src/features/support/useAttachmentObjectUrl.ts

diff --git a/apps/edr-freight-api/src/migrations/2320000000000-SupportChatAttachments.ts b/apps/edr-freight-api/src/migrations/2320000000000-SupportChatAttachments.ts
new file mode 100644
index 000000000..1f383f1da
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/2320000000000-SupportChatAttachments.ts
@@ -0,0 +1,50 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Let a support message carry files instead of text.
+ *
+ * No new table: chat attachments reuse the polymorphic `freight.files` record
+ * with `resource = 'support_message'` and `resource_id = <message id>`, the same
+ * way bookings/contracts/companies already store theirs.
+ *
+ * The only schema change is dropping NOT NULL from `support_messages.body`, so
+ * an attachment-only message can say "there is no text" rather than smuggling
+ * that fact through an empty string. DROP NOT NULL is a catalog-only change in
+ * Postgres — no table rewrite, no long lock — so this is safe on a live table.
+ *
+ * The partial index on (resource, resource_id) is what makes hydrating a page of
+ * messages one indexed lookup instead of a scan of every file row in the system.
+ */
+export class SupportChatAttachments2320000000000 implements MigrationInterface {
+  name = "SupportChatAttachments2320000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.support_messages
+      ALTER COLUMN body DROP NOT NULL
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_FILES_RESOURCE_LOOKUP"
+      ON freight.files (resource, resource_id)
+      WHERE deleted_at IS NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      DROP INDEX IF EXISTS freight."IDX_FILES_RESOURCE_LOOKUP"
+    `);
+
+    // Re-imposing NOT NULL would fail on any attachment-only message written
+    // while this migration was applied. Backfill those to '' first so the
+    // rollback is deterministic rather than dependent on production data.
+    await queryRunner.query(`
+      UPDATE freight.support_messages SET body = '' WHERE body IS NULL
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.support_messages
+      ALTER COLUMN body SET NOT NULL
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/files/files.controller.ts b/apps/edr-freight-api/src/modules/files/files.controller.ts
index 307e24985..6978ad446 100644
--- a/apps/edr-freight-api/src/modules/files/files.controller.ts
+++ b/apps/edr-freight-api/src/modules/files/files.controller.ts
@@ -1,12 +1,19 @@
+import { SUPPORT_ATTACHMENT_RESOURCE } from "@edr/types";
 import {
   Controller,
+  ForbiddenException,
   Get,
   Param,
   ParseUUIDPipe,
   Query,
   Res,
 } from "@nestjs/common";
-import { ApiBearerAuth, ApiOperation, ApiQuery, ApiTags } from "@nestjs/swagger";
+import {
+  ApiBearerAuth,
+  ApiOperation,
+  ApiQuery,
+  ApiTags,
+} from "@nestjs/swagger";
 import { Response } from "express";
 
 import { FilesService } from "./files.service";
@@ -23,13 +30,16 @@ export class FilesController {
   // Browser inline previews (<img>/<iframe>/<a>) that can't carry the Bearer
   // token should use a short-lived signed URL instead (FilesService.signUrl).
   // TODO: enforce ownership-by-resource here next (scope the file to the
-  // caller's booking/company before streaming).
+  // caller's booking/company before streaming). Until that lands, any resource
+  // whose files are cross-tenant sensitive must opt OUT of this route and expose
+  // its own checked endpoint — see the support_message case below.
   @ApiOperation({
     summary: "Stream a file by ID",
     description:
       "Global endpoint — streams any uploaded file directly from MinIO by its UUID. " +
       "No resource context (e.g. booking ID) required. Serves inline by default so " +
-      "the browser can preview it; pass ?download=1 to force a download.",
+      "the browser can preview it; pass ?download=1 to force a download. " +
+      "Support-chat attachments are NOT served here — use GET /support/attachments/:fileId.",
   })
   @ApiQuery({
     name: "download",
@@ -41,7 +51,19 @@ export class FilesController {
     @Query("download") download: string | undefined,
     @Res() res: Response,
   ) {
-    const { stream, record } = await this.filesService.streamById(fileId);
+    const record = await this.filesService.findById(fileId);
+
+    // Chat attachments are cross-tenant sensitive and this route has no
+    // ownership check, so a leaked/guessed UUID would hand one company's file to
+    // another. SupportAttachmentController scopes the caller to the owning
+    // thread; refuse here rather than quietly serving the bytes.
+    if (record.resource === SUPPORT_ATTACHMENT_RESOURCE) {
+      throw new ForbiddenException(
+        "Support chat attachments must be fetched via GET /support/attachments/:fileId.",
+      );
+    }
+
+    const { stream } = await this.filesService.streamById(fileId);
     const forceDownload = download === "1" || download === "true";
     const disposition = forceDownload ? "attachment" : "inline";
 
diff --git a/apps/edr-freight-api/src/modules/files/files.repository.ts b/apps/edr-freight-api/src/modules/files/files.repository.ts
index ea4bfd19e..a9e8bf761 100644
--- a/apps/edr-freight-api/src/modules/files/files.repository.ts
+++ b/apps/edr-freight-api/src/modules/files/files.repository.ts
@@ -1,7 +1,7 @@
 import { BaseRepository } from "@edr/api-common";
 import { Injectable } from "@nestjs/common";
 import { InjectRepository } from "@nestjs/typeorm";
-import { Repository } from "typeorm";
+import { In, Repository } from "typeorm";
 
 import { FileRecord } from "./entities/file.entity";
 
@@ -18,6 +18,21 @@ export class FilesRepository extends BaseRepository<FileRecord> {
     return this.repository.find({ where: { resourceId, resource } });
   }
 
+  /**
+   * Batch sibling of {@link findByResource} for hydrating a page of resources at
+   * once (a thread of chat messages, say) instead of one query per row.
+   */
+  async findByResourceIds(
+    resourceIds: string[],
+    resource: string,
+  ): Promise<FileRecord[]> {
+    if (resourceIds.length === 0) return [];
+    return this.repository.find({
+      where: { resourceId: In(resourceIds), resource },
+      order: { createdAt: "ASC" },
+    });
+  }
+
   findByCode(
     resourceId: string,
     resource: string,
diff --git a/apps/edr-freight-api/src/modules/files/files.service.ts b/apps/edr-freight-api/src/modules/files/files.service.ts
index aeb551b23..c799d896d 100644
--- a/apps/edr-freight-api/src/modules/files/files.service.ts
+++ b/apps/edr-freight-api/src/modules/files/files.service.ts
@@ -3,6 +3,7 @@ import {
   Injectable,
   NotFoundException,
 } from "@nestjs/common";
+import { randomUUID } from "crypto";
 import { Readable } from "stream";
 
 import { MinioService } from "../minio/minio.service";
@@ -78,8 +79,19 @@ export class FilesService {
     // percent-encoded in the URL and no longer match the MinIO key). The
     // human-readable name is preserved separately on the record below.
     const safeName = sanitizeObjectName(file.originalname);
-    const objectName = `${resource}/${resourceId}/${Date.now()}_${safeName}`;
-    const url = await this.minioService.uploadFile(objectName, file.buffer, file.mimetype);
+    // The random segment is load-bearing, not decoration. `Date.now()` alone is
+    // NOT unique across a batch: callers upload with Promise.all, every callback
+    // runs to its first await in the same tick, so they all read the same
+    // millisecond. Two files with one name in one batch — e.g. pasting two
+    // screenshots, which browsers both call "image.png" — would build identical
+    // keys, and the second putObject would overwrite the first while both rows
+    // persisted pointing at the same object.
+    const objectName = `${resource}/${resourceId}/${Date.now()}_${randomUUID().slice(0, 8)}_${safeName}`;
+    const url = await this.minioService.uploadFile(
+      objectName,
+      file.buffer,
+      file.mimetype,
+    );
 
     return this.filesRepository.create({
       resourceId,
@@ -175,6 +187,27 @@ export class FilesService {
     return this.filesRepository.findByResource(resourceId, resource);
   }
 
+  /**
+   * Files for many resources of one kind, grouped by resource id. Resources with
+   * no files are absent from the map (callers should default to `[]`).
+   */
+  async findByResourceIdsGrouped(
+    resourceIds: string[],
+    resource: string,
+  ): Promise<Map<string, FileRecord[]>> {
+    const records = await this.filesRepository.findByResourceIds(
+      resourceIds,
+      resource,
+    );
+    const grouped = new Map<string, FileRecord[]>();
+    for (const record of records) {
+      const bucket = grouped.get(record.resourceId);
+      if (bucket) bucket.push(record);
+      else grouped.set(record.resourceId, [record]);
+    }
+    return grouped;
+  }
+
   /**
    * Short-lived signed URL for a stored file's raw MinIO URL. The persisted
    * `url` is an un-signed object path that a browser cannot fetch directly;
@@ -190,7 +223,11 @@ export class FilesService {
     resource: string,
     code: string,
   ): Promise<FileRecord> {
-    const record = await this.filesRepository.findByCode(resourceId, resource, code);
+    const record = await this.filesRepository.findByCode(
+      resourceId,
+      resource,
+      code,
+    );
     if (!record)
       throw new NotFoundException(
         `File with code "${code}" not found for ${resource} ${resourceId}`,
@@ -198,7 +235,9 @@ export class FilesService {
     return record;
   }
 
-  async streamById(id: string): Promise<{ stream: Readable; record: FileRecord }> {
+  async streamById(
+    id: string,
+  ): Promise<{ stream: Readable; record: FileRecord }> {
     const record = await this.findById(id);
     const objectName = this.minioService.getObjectNameFromUrl(record.url);
     const stream = await this.minioService.getFileStream(objectName);
diff --git a/apps/edr-freight-api/src/modules/support-chat/attachment-upload.options.ts b/apps/edr-freight-api/src/modules/support-chat/attachment-upload.options.ts
new file mode 100644
index 000000000..ab85a49ce
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/support-chat/attachment-upload.options.ts
@@ -0,0 +1,25 @@
+import {
+  SUPPORT_ATTACHMENT_MAX_BYTES,
+  SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+} from "@edr/types";
+import { MulterOptions } from "@nestjs/platform-express/multer/interfaces/multer-options.interface";
+
+/** Multipart field name carrying chat files. */
+export const SUPPORT_ATTACHMENT_FIELD = "attachments";
+
+/**
+ * Multer-level caps for the chat send routes.
+ *
+ * These duplicate the checks in `SupportChatService.assertSendable` on purpose,
+ * and are not a substitute for them: Multer stops reading the socket once a part
+ * exceeds `fileSize`, so an oversized upload is cut off mid-stream instead of
+ * being buffered into memory and rejected after the fact. The service-level
+ * check is what produces the readable error message and covers callers that
+ * don't come through this interceptor.
+ */
+export const supportAttachmentMulterOptions: MulterOptions = {
+  limits: {
+    fileSize: SUPPORT_ATTACHMENT_MAX_BYTES,
+    files: SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/support-chat/dto/list-messages-query.dto.ts b/apps/edr-freight-api/src/modules/support-chat/dto/list-messages-query.dto.ts
new file mode 100644
index 000000000..76d29bfb6
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/support-chat/dto/list-messages-query.dto.ts
@@ -0,0 +1,30 @@
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { Type } from "class-transformer";
+import { IsInt, IsOptional, IsString, Max, Min } from "class-validator";
+
+/** Default page size for a thread — roughly two screens of bubbles. */
+export const SUPPORT_MESSAGES_DEFAULT_LIMIT = 30;
+export const SUPPORT_MESSAGES_MAX_LIMIT = 100;
+
+export class ListMessagesQueryDto {
+  @ApiPropertyOptional({
+    description:
+      "Opaque cursor from a previous response's `nextCursor`. Returns the page " +
+      "of messages immediately OLDER than the cursor. Omit for the newest page.",
+  })
+  @IsOptional()
+  @IsString()
+  before?: string;
+
+  @ApiPropertyOptional({
+    minimum: 1,
+    maximum: SUPPORT_MESSAGES_MAX_LIMIT,
+    default: SUPPORT_MESSAGES_DEFAULT_LIMIT,
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(SUPPORT_MESSAGES_MAX_LIMIT)
+  limit?: number;
+}
diff --git a/apps/edr-freight-api/src/modules/support-chat/dto/send-message.dto.ts b/apps/edr-freight-api/src/modules/support-chat/dto/send-message.dto.ts
index 89178ef63..37304e9a8 100644
--- a/apps/edr-freight-api/src/modules/support-chat/dto/send-message.dto.ts
+++ b/apps/edr-freight-api/src/modules/support-chat/dto/send-message.dto.ts
@@ -1,11 +1,15 @@
 import { SendSupportMessageDto as ISendSupportMessageDto } from "@edr/types";
-import { ApiProperty } from "@nestjs/swagger";
-import { IsString, MaxLength, MinLength } from "class-validator";
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { IsOptional, IsString, MaxLength } from "class-validator";
 
 export class SendMessageDto implements ISendSupportMessageDto {
-  @ApiProperty({ description: "Message text." })
+  @ApiPropertyOptional({
+    description:
+      "Message text. Optional only when the request carries attachments — the " +
+      "service rejects a message that is neither text nor files.",
+  })
+  @IsOptional()
   @IsString()
-  @MinLength(1)
   @MaxLength(4000)
-  body!: string;
+  body?: string;
 }
diff --git a/apps/edr-freight-api/src/modules/support-chat/entities/support-message.entity.ts b/apps/edr-freight-api/src/modules/support-chat/entities/support-message.entity.ts
index 443a1694f..b97fb76af 100644
--- a/apps/edr-freight-api/src/modules/support-chat/entities/support-message.entity.ts
+++ b/apps/edr-freight-api/src/modules/support-chat/entities/support-message.entity.ts
@@ -19,6 +19,10 @@ export class SupportMessage extends BaseEntity {
   @Column({ name: "author_name", type: "varchar", length: 200, nullable: true })
   authorName?: string | null;
 
-  @Column({ name: "body", type: "text" })
-  body!: string;
+  /**
+   * NULL for an attachment-only message. Nullable rather than "" so the absence
+   * of text is representable instead of guessed at; the DTO maps NULL → "".
+   */
+  @Column({ name: "body", type: "text", nullable: true })
+  body?: string | null;
 }
diff --git a/apps/edr-freight-api/src/modules/support-chat/message-cursor.ts b/apps/edr-freight-api/src/modules/support-chat/message-cursor.ts
new file mode 100644
index 000000000..54a7d6024
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/support-chat/message-cursor.ts
@@ -0,0 +1,54 @@
+import { BadRequestException } from "@nestjs/common";
+
+/**
+ * Keyset cursor for paging a thread backwards from newest.
+ *
+ * The cursor is just a message id. The sort key is the pair `(created_at, id)` —
+ * two messages can share a timestamp, and a cursor on a non-unique key either
+ * re-serves or skips the tied rows — but the *timestamp half is never sent over
+ * the wire*, because it cannot survive the trip.
+ *
+ * `support_messages.created_at` is `timestamptz(6)`; a JS `Date` holds only
+ * milliseconds, so the value TypeORM hands back is already truncated. Encoding
+ * that into the cursor and comparing against it would silently skip every row
+ * sharing the cursor's millisecond but earlier within it (`.254100` is not
+ * `< .254000`) — those rows would never appear on any page. Sending the id alone
+ * and letting Postgres look the real `(created_at, id)` up keeps the comparison
+ * at full precision on the server, where it was never lossy.
+ *
+ * Opaque on purpose (base64): clients must treat it as a token, so the sort key
+ * can change without a contract change.
+ *
+ * The passenger API's twin encodes a timestamp because its column is
+ * `TIMESTAMP(3)` — millisecond, matching JS exactly — so it has no such loss.
+ * The two formats are deliberately NOT interchangeable; each app reads only its
+ * own cursors.
+ */
+export function encodeMessageCursor(id: string): string {
+  return Buffer.from(id, "utf8").toString("base64url");
+}
+
+/**
+ * Parse a client-supplied cursor. Rejects anything malformed rather than
+ * silently falling back to "first page" — a corrupted cursor that degrades to
+ * page 1 makes an infinite scroll loop forever over the same rows.
+ */
+export function decodeMessageCursor(raw: string): string {
+  let id: string;
+  try {
+    id = Buffer.from(raw, "base64url").toString("utf8");
+  } catch {
+    throw new BadRequestException("Malformed pagination cursor.");
+  }
+
+  // The id goes into a parameterized query, but validate the shape anyway: a
+  // non-uuid can only be a mangled cursor, and failing loudly here beats an
+  // empty page that reads as "start of conversation".
+  if (
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)
+  ) {
+    throw new BadRequestException("Malformed pagination cursor.");
+  }
+
+  return id;
+}
diff --git a/apps/edr-freight-api/src/modules/support-chat/support-attachment.controller.ts b/apps/edr-freight-api/src/modules/support-chat/support-attachment.controller.ts
new file mode 100644
index 000000000..be7c78fdc
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/support-chat/support-attachment.controller.ts
@@ -0,0 +1,100 @@
+import { CurrentUser } from "@edr/api-common";
+import { SUPPORT_ATTACHMENT_RESOURCE } from "@edr/types";
+import {
+  Controller,
+  ForbiddenException,
+  Get,
+  NotFoundException,
+  Param,
+  ParseUUIDPipe,
+  Query,
+  Res,
+} from "@nestjs/common";
+import {
+  ApiBearerAuth,
+  ApiOperation,
+  ApiQuery,
+  ApiTags,
+} from "@nestjs/swagger";
+import { Response } from "express";
+
+import {
+  AuthUserPayload,
+  resolveAuthUserId,
+} from "../../common/resolve-auth-user-id";
+import { FilesService } from "../files/files.service";
+import { SupportChatService } from "./support-chat.service";
+
+/**
+ * Authenticated download for chat attachments.
+ *
+ * This exists instead of reusing `GET /files/:fileId` because that route streams
+ * any file to any authenticated caller who knows its UUID — fine-ish for a
+ * booking document the caller already had a link to, not fine for chat, where
+ * one customer guessing another's file id would be a cross-tenant leak. That
+ * route now refuses `support_message` files outright and points here.
+ *
+ * Inline previews still use the short-lived signed URL on the message DTO — a
+ * browser `<img>` can't send a Bearer token. This route is for explicit
+ * downloads and for clients that would rather stream through the API.
+ */
+@ApiTags("support-chat")
+@ApiBearerAuth()
+@Controller("support/attachments")
+export class SupportAttachmentController {
+  constructor(
+    private readonly files: FilesService,
+    private readonly chat: SupportChatService,
+  ) {}
+
+  @Get(":fileId")
+  @ApiOperation({
+    summary: "Download a support chat attachment",
+    description:
+      "Streams the file only if the caller is backoffice staff or belongs to the " +
+      "company that owns the thread the attachment was posted in.",
+  })
+  @ApiQuery({
+    name: "download",
+    required: false,
+    description: "Set to 1/true to force a download instead of inline preview.",
+  })
+  async download(
+    @CurrentUser() user: AuthUserPayload,
+    @Param("fileId", ParseUUIDPipe) fileId: string,
+    @Query("download") download: string | undefined,
+    @Res() res: Response,
+  ) {
+    const record = await this.files.findById(fileId);
+
+    // Don't let this route become a second general-purpose file endpoint: it can
+    // only vouch for chat attachments, so anything else is a 404 (not a 403 —
+    // no reason to confirm the id exists).
+    if (record.resource !== SUPPORT_ATTACHMENT_RESOURCE) {
+      throw new NotFoundException(`File ${fileId} not found`);
+    }
+
+    const allowed = await this.chat.canUserAccessMessage(
+      record.resourceId,
+      resolveAuthUserId(user),
+    );
+    if (!allowed) {
+      throw new ForbiddenException(
+        "This attachment belongs to another company's conversation.",
+      );
+    }
+
+    const { stream } = await this.files.streamById(fileId);
+    const forceDownload = download === "1" || download === "true";
+
+    res.setHeader("Content-Type", record.mimeType);
+    res.setHeader(
+      "Content-Disposition",
+      `${forceDownload ? "attachment" : "inline"}; filename="${record.name}"`,
+    );
+    // Private only — this response is scoped to one caller's authorization, so a
+    // shared cache must never reuse it for the next person asking.
+    res.setHeader("Cache-Control", "private, max-age=300");
+    stream.pipe(res);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/support-chat/support-chat-agent.controller.ts b/apps/edr-freight-api/src/modules/support-chat/support-chat-agent.controller.ts
index efeb918be..06fe9b2a9 100644
--- a/apps/edr-freight-api/src/modules/support-chat/support-chat-agent.controller.ts
+++ b/apps/edr-freight-api/src/modules/support-chat/support-chat-agent.controller.ts
@@ -1,5 +1,8 @@
 import { CurrentUser } from "@edr/api-common";
-import { SupportAuthorRole } from "@edr/types";
+import {
+  SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+  SupportAuthorRole,
+} from "@edr/types";
 import {
   Body,
   Controller,
@@ -8,14 +11,22 @@ import {
   ParseUUIDPipe,
   Post,
   Query,
+  UploadedFiles,
+  UseInterceptors,
 } from "@nestjs/common";
-import { ApiOperation, ApiTags } from "@nestjs/swagger";
+import { FilesInterceptor } from "@nestjs/platform-express";
+import { ApiBody, ApiConsumes, ApiOperation, ApiTags } from "@nestjs/swagger";
 
 import {
   AuthUserPayload,
   resolveAuthUserId,
 } from "../../common/resolve-auth-user-id";
+import {
+  SUPPORT_ATTACHMENT_FIELD,
+  supportAttachmentMulterOptions,
+} from "./attachment-upload.options";
 import { ListConversationsQueryDto } from "./dto/list-conversations-query.dto";
+import { ListMessagesQueryDto } from "./dto/list-messages-query.dto";
 import { SendMessageDto } from "./dto/send-message.dto";
 import { StartConversationDto } from "./dto/start-conversation.dto";
 import { SupportChatService } from "./support-chat.service";
@@ -41,19 +52,57 @@ export class SupportChatAgentController {
   }
 
   @Get("conversations/:id/messages")
-  @ApiOperation({ summary: "List messages in a thread" })
-  messages(@Param("id", ParseUUIDPipe) id: string) {
-    return this.service.getMessages(id);
+  @ApiOperation({
+    summary: "List messages in a thread (newest page first)",
+    description:
+      "Keyset-paginated backwards from the newest message. Omit `before` for " +
+      "the newest page, then pass the previous response's `nextCursor` to walk " +
+      "back through history. `nextCursor: null` means the thread's start.",
+  })
+  messages(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Query() query: ListMessagesQueryDto,
+  ) {
+    return this.service.getMessages(id, query);
   }
 
   @Post("conversations/:id/messages")
-  @ApiOperation({ summary: "Reply as an agent" })
+  @UseInterceptors(
+    FilesInterceptor(
+      SUPPORT_ATTACHMENT_FIELD,
+      SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+      supportAttachmentMulterOptions,
+    ),
+  )
+  // Accepts multipart (text + files) or plain JSON (text only) — Multer passes
+  // non-multipart requests straight through, so existing JSON clients are
+  // unaffected.
+  @ApiConsumes("multipart/form-data", "application/json")
+  @ApiBody({
+    schema: {
+      type: "object",
+      properties: {
+        body: { type: "string" },
+        attachments: {
+          type: "array",
+          items: { type: "string", format: "binary" },
+        },
+      },
+    },
+  })
+  @ApiOperation({ summary: "Reply as an agent, optionally with attachments" })
   send(
     @CurrentUser() user: AuthUserPayload,
     @Param("id", ParseUUIDPipe) id: string,
     @Body() body: SendMessageDto,
+    @UploadedFiles() attachments?: Express.Multer.File[],
   ) {
-    return this.service.sendAsAgent(id, resolveAuthUserId(user), body.body);
+    return this.service.sendAsAgent(
+      id,
+      resolveAuthUserId(user),
+      body.body,
+      attachments ?? [],
+    );
   }
 
   @Post("conversations/:id/read")
diff --git a/apps/edr-freight-api/src/modules/support-chat/support-chat.controller.ts b/apps/edr-freight-api/src/modules/support-chat/support-chat.controller.ts
index 8d20ee91f..88686bfa8 100644
--- a/apps/edr-freight-api/src/modules/support-chat/support-chat.controller.ts
+++ b/apps/edr-freight-api/src/modules/support-chat/support-chat.controller.ts
@@ -1,12 +1,29 @@
 import { CurrentUser } from "@edr/api-common";
-import { SupportAuthorRole } from "@edr/types";
-import { Body, Controller, Get, Post } from "@nestjs/common";
-import { ApiOperation, ApiTags } from "@nestjs/swagger";
+import {
+  SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+  SupportAuthorRole,
+} from "@edr/types";
+import {
+  Body,
+  Controller,
+  Get,
+  Post,
+  Query,
+  UploadedFiles,
+  UseInterceptors,
+} from "@nestjs/common";
+import { FilesInterceptor } from "@nestjs/platform-express";
+import { ApiBody, ApiConsumes, ApiOperation, ApiTags } from "@nestjs/swagger";
 
 import {
   AuthUserPayload,
   resolveAuthUserId,
 } from "../../common/resolve-auth-user-id";
+import {
+  SUPPORT_ATTACHMENT_FIELD,
+  supportAttachmentMulterOptions,
+} from "./attachment-upload.options";
+import { ListMessagesQueryDto } from "./dto/list-messages-query.dto";
 import { SendMessageDto } from "./dto/send-message.dto";
 import { SupportChatService } from "./support-chat.service";
 
@@ -29,17 +46,55 @@ export class SupportChatController {
   }
 
   @Get("conversation/messages")
-  @ApiOperation({ summary: "Messages in my company's support thread" })
-  messages(@CurrentUser() user: AuthUserPayload) {
-    return this.service.getCustomerMessages(resolveAuthUserId(user));
+  @ApiOperation({
+    summary: "Messages in my company's support thread (newest page first)",
+    description:
+      "Keyset-paginated backwards from the newest message. Omit `before` for " +
+      "the newest page, then pass the previous response's `nextCursor` to walk " +
+      "back through history. `nextCursor: null` means the thread's start.",
+  })
+  messages(
+    @CurrentUser() user: AuthUserPayload,
+    @Query() query: ListMessagesQueryDto,
+  ) {
+    return this.service.getCustomerMessages(resolveAuthUserId(user), query);
   }
 
   @Post("conversation/messages")
-  @ApiOperation({
-    summary: "Send a message as the customer, opening the thread if needed",
+  @UseInterceptors(
+    FilesInterceptor(
+      SUPPORT_ATTACHMENT_FIELD,
+      SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+      supportAttachmentMulterOptions,
+    ),
+  )
+  @ApiConsumes("multipart/form-data", "application/json")
+  @ApiBody({
+    schema: {
+      type: "object",
+      properties: {
+        body: { type: "string" },
+        attachments: {
+          type: "array",
+          items: { type: "string", format: "binary" },
+        },
+      },
+    },
   })
-  send(@CurrentUser() user: AuthUserPayload, @Body() body: SendMessageDto) {
-    return this.service.sendAsCustomer(resolveAuthUserId(user), body.body);
+  @ApiOperation({
+    summary:
+      "Send a message as the customer (optionally with attachments), opening the thread if needed",
+  })
+  send(
+    @CurrentUser() user: AuthUserPayload,
+    @Body() body: SendMessageDto,
+    @UploadedFiles() attachments?: Express.Multer.File[],
+  ) {
+    return this.service.sendAsCustomer(
+      resolveAuthUserId(user),
+      body.body,
+      attachments ?? [],
+    );
   }
 
   @Post("conversation/read")
diff --git a/apps/edr-freight-api/src/modules/support-chat/support-chat.module.ts b/apps/edr-freight-api/src/modules/support-chat/support-chat.module.ts
index 34accab44..e70bcb741 100644
--- a/apps/edr-freight-api/src/modules/support-chat/support-chat.module.ts
+++ b/apps/edr-freight-api/src/modules/support-chat/support-chat.module.ts
@@ -3,9 +3,11 @@ import { TypeOrmModule } from "@nestjs/typeorm";
 
 import { BackofficeModule } from "../backoffice/backoffice.module";
 import { CompaniesModule } from "../companies/companies.module";
+import { FilesModule } from "../files/files.module";
 import { NotificationInboxModule } from "../notification-inbox/notification-inbox.module";
 import { SupportConversation } from "./entities/support-conversation.entity";
 import { SupportMessage } from "./entities/support-message.entity";
+import { SupportAttachmentController } from "./support-attachment.controller";
 import { SupportChatAgentController } from "./support-chat-agent.controller";
 import { SupportChatController } from "./support-chat.controller";
 import { SupportChatGateway } from "./support-chat.gateway";
@@ -23,13 +25,22 @@ import { SupportMessageRepository } from "./support-message.repository";
     BackofficeModule,
     // WsAuthService — reused handshake authentication for the gateway.
     NotificationInboxModule,
+    // FilesService — chat attachments are stored as polymorphic file records.
+    FilesModule,
+  ],
+  controllers: [
+    SupportChatController,
+    SupportChatAgentController,
+    SupportAttachmentController,
   ],
-  controllers: [SupportChatController, SupportChatAgentController],
   providers: [
     SupportConversationRepository,
     SupportMessageRepository,
     SupportChatGateway,
     SupportChatService,
   ],
+  // FilesController's ownership check for `support_message` files defers to this
+  // service — see SupportAttachmentAccess.
+  exports: [SupportChatService],
 })
 export class SupportChatModule {}
diff --git a/apps/edr-freight-api/src/modules/support-chat/support-chat.service.ts b/apps/edr-freight-api/src/modules/support-chat/support-chat.service.ts
index 70de1ce11..d845f6a86 100644
--- a/apps/edr-freight-api/src/modules/support-chat/support-chat.service.ts
+++ b/apps/edr-freight-api/src/modules/support-chat/support-chat.service.ts
@@ -1,22 +1,37 @@
 import {
+  isSupportAttachmentAllowed,
   SendSupportMessageResult,
+  SUPPORT_ATTACHMENT_MAX_BYTES,
+  SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+  SUPPORT_ATTACHMENT_RESOURCE,
+  SupportAttachmentDto,
   SupportAuthorRole,
   SupportConversationDto,
   SupportConversationListResult,
   SupportMessageDto,
+  SupportMessageListResult,
 } from "@edr/types";
 import {
+  BadRequestException,
   ForbiddenException,
   Injectable,
   NotFoundException,
 } from "@nestjs/common";
 import { QueryFailedError } from "typeorm";
 
+import { BackofficeService } from "../backoffice/backoffice.service";
 import { CompaniesService } from "../companies/companies.service";
 import { ExternalProfileRepository } from "../companies/external-profile.repository";
+import { FileRecord } from "../files/entities/file.entity";
+import { FilesService } from "../files/files.service";
 import { ListConversationsQueryDto } from "./dto/list-conversations-query.dto";
+import {
+  ListMessagesQueryDto,
+  SUPPORT_MESSAGES_DEFAULT_LIMIT,
+} from "./dto/list-messages-query.dto";
 import { SupportConversation } from "./entities/support-conversation.entity";
 import { SupportMessage } from "./entities/support-message.entity";
+import { decodeMessageCursor, encodeMessageCursor } from "./message-cursor";
 import { SupportChatGateway } from "./support-chat.gateway";
 import { SupportConversationRepository } from "./support-conversation.repository";
 import { SupportMessageRepository } from "./support-message.repository";
@@ -30,6 +45,9 @@ interface CustomerContext {
 /** Postgres unique_violation — the one-thread-per-company index fired. */
 const PG_UNIQUE_VIOLATION = "23505";
 
+/** Stand-in preview for a message that is nothing but files. */
+const ATTACHMENT_ONLY_PREVIEW = "📎";
+
 @Injectable()
 export class SupportChatService {
   constructor(
@@ -38,6 +56,8 @@ export class SupportChatService {
     private readonly gateway: SupportChatGateway,
     private readonly externalProfiles: ExternalProfileRepository,
     private readonly companies: CompaniesService,
+    private readonly files: FilesService,
+    private readonly backoffice: BackofficeService,
   ) {}
 
   // ---- customer (portal) -------------------------------------------------
@@ -51,7 +71,9 @@ export class SupportChatService {
     userId: string,
   ): Promise<SupportConversationDto | null> {
     const ctx = await this.resolveCustomer(userId);
-    const conversation = await this.conversations.findByCompanyId(ctx.companyId);
+    const conversation = await this.conversations.findByCompanyId(
+      ctx.companyId,
+    );
     if (!conversation) return null;
     const unread = await this.messages.unreadCountsByConversation(
       [conversation.id],
@@ -63,17 +85,23 @@ export class SupportChatService {
     );
   }
 
-  async getCustomerMessages(userId: string): Promise<SupportMessageDto[]> {
+  async getCustomerMessages(
+    userId: string,
+    query: ListMessagesQueryDto = {},
+  ): Promise<SupportMessageListResult> {
     const ctx = await this.resolveCustomer(userId);
-    const conversation = await this.conversations.findByCompanyId(ctx.companyId);
-    if (!conversation) return [];
-    return this.listMessages(conversation.id);
+    const conversation = await this.conversations.findByCompanyId(
+      ctx.companyId,
+    );
+    if (!conversation) return { items: [], nextCursor: null };
+    return this.listMessages(conversation.id, query);
   }
 
   /** Send as the customer, opening the thread if this is the first message. */
   async sendAsCustomer(
     userId: string,
-    body: string,
+    body: string | undefined,
+    attachments: Express.Multer.File[] = [],
   ): Promise<SendSupportMessageResult> {
     const ctx = await this.resolveCustomer(userId);
     const conversation = await this.getOrCreate(
@@ -87,16 +115,19 @@ export class SupportChatService {
       SupportAuthorRole.CUSTOMER,
       body,
       ctx.authorName,
+      attachments,
     );
     return {
       conversation: this.toConversationDto(updated, 0),
-      message: this.toMessageDto(message),
+      message: message,
     };
   }
 
   async markCustomerRead(userId: string): Promise<{ unreadCount: number }> {
     const ctx = await this.resolveCustomer(userId);
-    const conversation = await this.conversations.findByCompanyId(ctx.companyId);
+    const conversation = await this.conversations.findByCompanyId(
+      ctx.companyId,
+    );
     if (conversation) {
       await this.conversations.update(conversation.id, {
         customerLastReadAt: new Date(),
@@ -145,7 +176,8 @@ export class SupportChatService {
   async sendAsAgent(
     conversationId: string,
     userId: string,
-    body: string,
+    body: string | undefined,
+    attachments: Express.Multer.File[] = [],
   ): Promise<SupportMessageDto> {
     const conversation = await this.requireConversation(conversationId);
     const { message } = await this.appendMessage(
@@ -153,8 +185,10 @@ export class SupportChatService {
       userId,
       SupportAuthorRole.AGENT,
       body,
+      undefined,
+      attachments,
     );
-    return this.toMessageDto(message);
+    return message;
   }
 
   async markAgentRead(
@@ -171,18 +205,56 @@ export class SupportChatService {
   // ---- shared ------------------------------------------------------------
 
   /**
-   * A thread's messages. Pass `asCustomerUserId` to enforce that the caller's
-   * company owns it (portal route); omit for agents, who see every thread.
+   * One page of a thread's messages, newest page first. Pass `asCustomerUserId`
+   * to enforce that the caller's company owns it (portal route); omit for
+   * agents, who see every thread.
    */
   async getMessages(
     conversationId: string,
+    query: ListMessagesQueryDto = {},
     asCustomerUserId?: string,
-  ): Promise<SupportMessageDto[]> {
+  ): Promise<SupportMessageListResult> {
     const conversation = await this.requireConversation(conversationId);
     if (asCustomerUserId) {
       await this.assertCustomerOwns(conversation, asCustomerUserId);
     }
-    return this.listMessages(conversationId);
+    return this.listMessages(conversationId, query);
+  }
+
+  /**
+   * May `userId` read the message that a chat attachment hangs off? Backstop for
+   * the file-download route, which otherwise streams any file to any
+   * authenticated caller who knows its UUID.
+   *
+   * Backoffice staff see every thread (they work a shared inbox); a portal user
+   * sees only their own company's. Fails **closed** — an unresolvable message,
+   * conversation, or staff list denies rather than falls through, since the
+   * caller uses this to decide whether to hand over raw bytes.
+   */
+  async canUserAccessMessage(
+    messageId: string,
+    userId: string,
+  ): Promise<boolean> {
+    const message = await this.messages.findById(messageId);
+    if (!message) return false;
+    const conversation = await this.conversations.findById(
+      message.conversationId,
+    );
+    if (!conversation) return false;
+
+    try {
+      const staffIds = await this.backoffice.getAllCurrentEmployeeUserIds();
+      if (staffIds.includes(userId)) return true;
+    } catch {
+      // Staff lookup is best-effort for room-joining in the gateway, but here it
+      // gates bytes: on failure fall through to the (stricter) company check
+      // rather than assuming staff.
+    }
+
+    const profile = await this.externalProfiles.findByUserId(userId);
+    return Boolean(
+      profile?.companyId && profile.companyId === conversation.companyId,
+    );
   }
 
   async unreadCount(
@@ -237,29 +309,86 @@ export class SupportChatService {
 
   private async listMessages(
     conversationId: string,
-  ): Promise<SupportMessageDto[]> {
-    const rows = await this.messages.listByConversation(conversationId);
-    return rows.map((m) => this.toMessageDto(m));
+    query: ListMessagesQueryDto,
+  ): Promise<SupportMessageListResult> {
+    const limit = query.limit ?? SUPPORT_MESSAGES_DEFAULT_LIMIT;
+    const before = query.before ? decodeMessageCursor(query.before) : undefined;
+
+    // The repo returns newest-first and over-fetches by one to probe for a
+    // further page.
+    const rows = await this.messages.listByConversation(
+      conversationId,
+      limit,
+      before,
+    );
+    const hasMore = rows.length > limit;
+    const page = hasMore ? rows.slice(0, limit) : rows;
+
+    const oldest = page[page.length - 1];
+    const nextCursor =
+      hasMore && oldest ? encodeMessageCursor(oldest.id) : null;
+
+    // Flip to oldest-first so the client can prepend a page as one block.
+    const items = await this.toMessageDtos([...page].reverse());
+    return { items, nextCursor };
   }
 
-  /** Persist a message, bump the conversation's denormalized fields, emit live. */
+  /**
+   * Persist a message (plus any attachments), bump the conversation's
+   * denormalized fields, emit live.
+   *
+   * Files are validated *before* the row is written: a rejected upload should
+   * leave no message behind, and a half-uploaded batch is worse than none.
+   */
   private async appendMessage(
     conversation: SupportConversation,
     userId: string,
     role: SupportAuthorRole,
-    body: string,
+    body: string | undefined,
     authorName?: string | null,
-  ): Promise<{ conversation: SupportConversation; message: SupportMessage }> {
+    attachments: Express.Multer.File[] = [],
+  ): Promise<{
+    conversation: SupportConversation;
+    message: SupportMessageDto;
+  }> {
+    const text = (body ?? "").trim();
+    this.assertSendable(text, attachments);
+
     const message = await this.messages.create({
       conversationId: conversation.id,
       authorUserId: userId,
       authorRole: role,
       authorName: authorName ?? null,
-      body,
+      // NULL, not "", so "this message has no text" is representable rather than
+      // inferred. The DTO flattens it back to "" for rendering.
+      body: text || null,
     });
 
+    // The row has to exist before the files, since each one is stored against
+    // `resourceId = message.id`. That leaves a window: if a upload fails here,
+    // the message is already committed. Undo it rather than leave the thread
+    // with a permanently blank bubble — there is no delete flow, so an orphan
+    // would be unremovable, and an attachment-only message that lost its files
+    // has no content at all.
+    let stored: FileRecord[];
+    try {
+      stored = await Promise.all(
+        attachments.map((file) =>
+          this.files.upload({
+            resourceId: message.id,
+            resource: SUPPORT_ATTACHMENT_RESOURCE,
+            code: "attachment",
+            file,
+          }),
+        ),
+      );
+    } catch (error) {
+      await this.messages.softDelete(message.id);
+      throw error;
+    }
+
     conversation.lastMessageAt = message.createdAt;
-    conversation.lastMessagePreview = body.slice(0, 280);
+    conversation.lastMessagePreview = this.buildPreview(text, stored);
     conversation.lastMessageAuthorRole = role;
     await this.conversations.update(conversation.id, {
       lastMessageAt: conversation.lastMessageAt,
@@ -267,13 +396,55 @@ export class SupportChatService {
       lastMessageAuthorRole: role,
     });
 
+    const messageDto = await this.toMessageDto(message, stored);
     const dto = this.toConversationDto(conversation, 0);
-    this.gateway.emitMessage(
-      conversation.companyId,
-      dto,
-      this.toMessageDto(message),
-    );
-    return { conversation, message };
+    this.gateway.emitMessage(conversation.companyId, dto, messageDto);
+    return { conversation, message: messageDto };
+  }
+
+  /**
+   * Guard the chat-specific upload rules. These are tighter than
+   * `FilesService.upload`'s own defence-in-depth checks (25MB, wider MIME set),
+   * which exist for scanned business documents — chat files are pushed at
+   * another human, so the allowlist is narrower and SVG is excluded outright.
+   */
+  private assertSendable(
+    text: string,
+    attachments: Express.Multer.File[],
+  ): void {
+    if (!text && attachments.length === 0) {
+      throw new BadRequestException(
+        "A message needs text or at least one attachment.",
+      );
+    }
+    if (attachments.length > SUPPORT_ATTACHMENT_MAX_PER_MESSAGE) {
+      throw new BadRequestException(
+        `At most ${SUPPORT_ATTACHMENT_MAX_PER_MESSAGE} files per message.`,
+      );
+    }
+    for (const file of attachments) {
+      if (!isSupportAttachmentAllowed(file.mimetype)) {
+        throw new BadRequestException(
+          `Unsupported attachment type: ${file.mimetype}`,
+        );
+      }
+      if (file.size > SUPPORT_ATTACHMENT_MAX_BYTES) {
+        throw new BadRequestException(
+          `"${file.originalname}" exceeds the ${
+            SUPPORT_ATTACHMENT_MAX_BYTES / (1024 * 1024)
+          }MB attachment limit.`,
+        );
+      }
+    }
+  }
+
+  /** Inbox preview line — falls back to the filenames when there's no text. */
+  private buildPreview(text: string, attachments: FileRecord[]): string {
+    if (text) return text.slice(0, 280);
+    if (attachments.length === 1) {
+      return `${ATTACHMENT_ONLY_PREVIEW} ${attachments[0].name}`.slice(0, 280);
+    }
+    return `${ATTACHMENT_ONLY_PREVIEW} ${attachments.length} files`;
   }
 
   private async buildListResult(
@@ -320,7 +491,9 @@ export class SupportChatService {
   ): Promise<CustomerContext> {
     const ctx = await this.resolveCustomer(userId);
     if (conversation.companyId !== ctx.companyId) {
-      throw new ForbiddenException("This conversation belongs to another company.");
+      throw new ForbiddenException(
+        "This conversation belongs to another company.",
+      );
     }
     return ctx;
   }
@@ -353,15 +526,58 @@ export class SupportChatService {
     };
   }
 
-  private toMessageDto(m: SupportMessage): SupportMessageDto {
+  /** Hydrate + map a page of messages, batching the attachment lookup. */
+  private async toMessageDtos(
+    rows: SupportMessage[],
+  ): Promise<SupportMessageDto[]> {
+    if (rows.length === 0) return [];
+    const grouped = await this.files.findByResourceIdsGrouped(
+      rows.map((r) => r.id),
+      SUPPORT_ATTACHMENT_RESOURCE,
+    );
+    return Promise.all(
+      rows.map((r) => this.toMessageDto(r, grouped.get(r.id) ?? [])),
+    );
+  }
+
+  private async toMessageDto(
+    m: SupportMessage,
+    attachments: FileRecord[],
+  ): Promise<SupportMessageDto> {
     return {
       id: m.id,
       conversationId: m.conversationId,
       authorUserId: m.authorUserId,
       authorRole: m.authorRole,
       authorName: m.authorName ?? null,
-      body: m.body,
+      body: m.body ?? "",
+      attachments: attachments.map((a) => this.toAttachmentDto(a)),
       createdAt: new Date(m.createdAt).toISOString(),
     };
   }
+
+  /**
+   * Where the browser fetches the bytes: the API's own ownership-checked stream
+   * route, NOT a presigned MinIO URL.
+   *
+   * Presigned object URLs are not reachable from the browser in this deployment
+   * — the same reason every other file in the app streams through
+   * `GET /api/files/:id` rather than a signed URL (see the `fileViewUrl` helper
+   * on the web side, and the minio-js port-443 signature quirk noted there). Chat
+   * attachments stream through `GET /api/support/attachments/:id`, which runs the
+   * same-company / staff ownership check before serving a byte.
+   *
+   * A root-relative path; the web app prepends its API origin. The `<img>` sends
+   * the `auth-token` cookie automatically (same-site across dev ports), which is
+   * how the guard authenticates a request that can't carry a bearer header.
+   */
+  private toAttachmentDto(f: FileRecord): SupportAttachmentDto {
+    return {
+      id: f.id,
+      name: f.name,
+      mimeType: f.mimeType,
+      size: f.size,
+      url: `/api/support/attachments/${f.id}`,
+    };
+  }
 }
diff --git a/apps/edr-freight-api/src/modules/support-chat/support-message.repository.ts b/apps/edr-freight-api/src/modules/support-chat/support-message.repository.ts
index 827035320..3858b2a64 100644
--- a/apps/edr-freight-api/src/modules/support-chat/support-message.repository.ts
+++ b/apps/edr-freight-api/src/modules/support-chat/support-message.repository.ts
@@ -16,12 +16,54 @@ export class SupportMessageRepository extends BaseRepository<SupportMessage> {
     super(repo);
   }
 
-  /** All messages of a conversation, oldest first. */
-  async listByConversation(conversationId: string): Promise<SupportMessage[]> {
-    return this.repository.find({
-      where: { conversationId },
-      order: { createdAt: "ASC" },
-    });
+  /**
+   * One page of a thread, walking backwards from newest.
+   *
+   * Returns **newest-first** and takes one row more than asked, so the caller
+   * can tell "there is another page" from "this page happened to be full"
+   * without a second COUNT. The caller trims the probe row and flips the page
+   * to oldest-first for rendering.
+   *
+   * Rides IDX_SUPPORT_MSG_CONV_CREATED (conversation_id, created_at); the id in
+   * the keyset is a tiebreak only and doesn't need its own index.
+   */
+  async listByConversation(
+    conversationId: string,
+    limit: number,
+    beforeId?: string,
+  ): Promise<SupportMessage[]> {
+    const qb = this.repository
+      .createQueryBuilder("m")
+      .where("m.conversation_id = :conversationId", { conversationId })
+      // createQueryBuilder bypasses TypeORM's soft-delete filter, unlike find().
+      .andWhere("m.deleted_at IS NULL");
+
+    if (beforeId) {
+      // Row-value comparison: strictly older than the cursor row in
+      // (created_at, id) order.
+      //
+      // The cursor's timestamp is read back from the row itself rather than
+      // passed in. `created_at` is timestamptz(6) but a JS Date only holds
+      // milliseconds, so a timestamp that made the round-trip through the API
+      // would arrive truncated — and `.254100 < .254000` is false, so every row
+      // sharing the cursor's millisecond but earlier within it would be skipped
+      // on every page, permanently. Postgres compares the stored values at full
+      // precision instead.
+      qb.andWhere(
+        `(m.created_at, m.id) < (
+           SELECT c.created_at, c.id
+           FROM freight.support_messages c
+           WHERE c.id = :cursorId
+         )`,
+        { cursorId: beforeId },
+      );
+    }
+
+    return qb
+      .orderBy("m.created_at", "DESC")
+      .addOrderBy("m.id", "DESC")
+      .take(limit + 1)
+      .getMany();
   }
 
   /**
diff --git a/apps/edr-freight-web/backoffice/src/features/support/AttachmentDraftBar.tsx b/apps/edr-freight-web/backoffice/src/features/support/AttachmentDraftBar.tsx
new file mode 100644
index 000000000..e8d742e88
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/features/support/AttachmentDraftBar.tsx
@@ -0,0 +1,78 @@
+import { ActionIcon, Box, Group, Image, Paper, Text } from "@mantine/core";
+import { FileText, X } from "lucide-react";
+
+import { formatBytes } from "./MessageAttachments";
+import type { PendingAttachment } from "./useAttachmentDraft";
+
+/**
+ * The staged-files strip above the composer. Shows what will be sent and lets
+ * the agent drop any of it before hitting send.
+ */
+export function AttachmentDraftBar({
+  attachments,
+  onRemove,
+}: {
+  attachments: PendingAttachment[];
+  onRemove: (id: string) => void;
+}) {
+  if (attachments.length === 0) return null;
+
+  return (
+    <Group gap="xs" mb="xs" wrap="wrap">
+      {attachments.map((a) => (
+        <Paper
+          key={a.id}
+          withBorder
+          radius="md"
+          p={4}
+          style={{ position: "relative" }}
+        >
+          <Group gap={6} wrap="nowrap" pr={16}>
+            {a.previewUrl ? (
+              <Image
+                src={a.previewUrl}
+                alt={a.file.name}
+                w={36}
+                h={36}
+                radius="sm"
+                fit="cover"
+              />
+            ) : (
+              <Box
+                w={36}
+                h={36}
+                style={{
+                  display: "grid",
+                  placeItems: "center",
+                  background: "var(--mantine-color-gray-1)",
+                  borderRadius: 4,
+                }}
+              >
+                <FileText size={16} />
+              </Box>
+            )}
+            <Box style={{ minWidth: 0, maxWidth: 120 }}>
+              <Text size="xs" fw={600} truncate>
+                {a.file.name}
+              </Text>
+              <Text size="10px" c="dimmed">
+                {formatBytes(a.file.size)}
+              </Text>
+            </Box>
+          </Group>
+          <ActionIcon
+            size="xs"
+            radius="xl"
+            color="gray"
+            variant="filled"
+            aria-label={`Remove ${a.file.name}`}
+            onClick={() => onRemove(a.id)}
+            style={{ position: "absolute", top: -6, right: -6 }}
+          >
+            <X size={10} />
+          </ActionIcon>
+        </Paper>
+      ))}
+    </Group>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/features/support/MessageAttachments.tsx b/apps/edr-freight-web/backoffice/src/features/support/MessageAttachments.tsx
new file mode 100644
index 000000000..e4d0585aa
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/features/support/MessageAttachments.tsx
@@ -0,0 +1,122 @@
+import {
+  isSupportAttachmentImage,
+  type SupportAttachmentDto,
+} from "@edr/types";
+import { Box, Group, Image, Loader, Paper, Stack, Text } from "@mantine/core";
+import { FileText, ImageOff } from "lucide-react";
+
+import { useAttachmentObjectUrl } from "./useAttachmentObjectUrl";
+
+/** Human-readable size — kept coarse; nobody needs bytes in a chat bubble. */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** Cap the bubble: a tall screenshot would push the conversation off-screen. */
+const THUMB = { maxHeight: 220, maxWidth: 260 } as const;
+
+/**
+ * One image attachment. Its own component because the bytes are fetched through
+ * the authenticated client (see {@link useAttachmentObjectUrl}) and a hook can't
+ * be called from inside a `.map()`.
+ */
+function ImageAttachment({
+  a,
+  onView,
+}: {
+  a: SupportAttachmentDto;
+  onView: (a: SupportAttachmentDto, src: string) => void;
+}) {
+  const { src, failed } = useAttachmentObjectUrl(a.url);
+
+  if (failed) {
+    return (
+      <Group gap={6} c="dimmed">
+        <ImageOff size={14} />
+        <Text size="xs">Couldn't load {a.name}</Text>
+      </Group>
+    );
+  }
+
+  if (!src) {
+    return (
+      <Box
+        style={{
+          width: THUMB.maxWidth,
+          height: 140,
+          display: "grid",
+          placeItems: "center",
+          background: "var(--mantine-color-gray-1)",
+          borderRadius: 8,
+        }}
+      >
+        <Loader size="xs" color="edr-green" />
+      </Box>
+    );
+  }
+
+  return (
+    <Box
+      onClick={() => onView(a, src)}
+      style={{ cursor: "zoom-in", borderRadius: 8, overflow: "hidden" }}
+    >
+      <Image src={src} alt={a.name} radius="md" fit="cover" style={THUMB} />
+    </Box>
+  );
+}
+
+/**
+ * Attachments inside a message bubble: images as thumbnails, everything else as
+ * a labelled file row. Non-images are not fetched until opened — pulling every
+ * document in a thread just to draw a filename would be wasteful.
+ */
+export function MessageAttachments({
+  attachments,
+  mine,
+  onView,
+  onOpenFile,
+}: {
+  attachments: SupportAttachmentDto[];
+  mine: boolean;
+  onView: (a: SupportAttachmentDto, src: string) => void;
+  onOpenFile: (a: SupportAttachmentDto) => void;
+}) {
+  if (attachments.length === 0) return null;
+
+  return (
+    <Stack gap={6} mt={6}>
+      {attachments.map((a) =>
+        isSupportAttachmentImage(a.mimeType) ? (
+          <ImageAttachment key={a.id} a={a} onView={onView} />
+        ) : (
+          <Paper
+            key={a.id}
+            onClick={() => onOpenFile(a)}
+            px="sm"
+            py={6}
+            radius="md"
+            style={{
+              cursor: "pointer",
+              background: mine ? "rgba(255,255,255,0.16)" : "white",
+              border: mine ? "none" : "1px solid var(--mantine-color-gray-3)",
+            }}
+          >
+            <Group gap={8} wrap="nowrap">
+              <FileText size={16} style={{ flexShrink: 0 }} />
+              <Box style={{ minWidth: 0 }}>
+                <Text size="xs" fw={600} truncate>
+                  {a.name}
+                </Text>
+                <Text size="10px" opacity={0.75}>
+                  {formatBytes(a.size)}
+                </Text>
+              </Box>
+            </Group>
+          </Paper>
+        ),
+      )}
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/features/support/supportApi.ts b/apps/edr-freight-web/backoffice/src/features/support/supportApi.ts
index 8047fc822..de61a2eec 100644
--- a/apps/edr-freight-web/backoffice/src/features/support/supportApi.ts
+++ b/apps/edr-freight-web/backoffice/src/features/support/supportApi.ts
@@ -1,8 +1,8 @@
 import type {
-  SendSupportMessageDto,
   SupportConversationDto,
   SupportConversationListResult,
   SupportMessageDto,
+  SupportMessageListResult,
 } from "@edr/types";
 
 import { api } from "@/auth/http";
@@ -14,6 +14,33 @@ export interface ListConversationsParams {
   limit?: number;
 }
 
+export interface ListMessagesParams {
+  /** Opaque cursor from the previous page's `nextCursor`. */
+  before?: string;
+  limit?: number;
+}
+
+/** What the composer hands over: text, files, or both (never neither). */
+export interface SendMessageInput {
+  body?: string;
+  attachments?: File[];
+}
+
+/**
+ * A message with files goes as multipart so the server can persist them against
+ * the message it creates in the same request; text-only stays JSON. Letting
+ * axios set the multipart boundary itself is deliberate — setting
+ * `Content-Type` by hand omits the boundary and the request fails to parse.
+ */
+function toRequestBody(input: SendMessageInput): FormData | { body?: string } {
+  if (!input.attachments?.length) return { body: input.body };
+
+  const form = new FormData();
+  if (input.body) form.append("body", input.body);
+  for (const file of input.attachments) form.append("attachments", file);
+  return form;
+}
+
 /**
  * Backoffice (agent) support-chat REST calls. The backoffice axios `api`
  * response interceptor already unwraps the `{ success, data }` envelope, so
@@ -29,19 +56,39 @@ export const supportApi = {
     );
     return data;
   },
-  listMessages: async (id: string): Promise<SupportMessageDto[]> => {
-    const { data } = await api.get<SupportMessageDto[]>(
+  listMessages: async (
+    id: string,
+    params: ListMessagesParams = {},
+  ): Promise<SupportMessageListResult> => {
+    const { data } = await api.get<SupportMessageListResult>(
       `/support/agent/conversations/${id}/messages`,
+      { params },
     );
     return data;
   },
+  /**
+   * Attachment bytes, fetched through the authenticated client.
+   *
+   * Deliberately not a direct `<img src={url}>`: the API guard reads the bearer
+   * token from the Authorization header only — there is no cookie fallback — and
+   * an `<img>` request cannot carry one, so a direct src is an unavoidable 401.
+   * Same reason `filesService.download` exists for booking documents. The caller
+   * wraps this blob in an object URL.
+   */
+  fetchAttachment: async (relativeUrl: string): Promise<Blob> => {
+    // The DTO path is absolute from the API root (`/api/...`), but this client's
+    // baseURL already ends in `/api` — drop the duplicate prefix.
+    const path = relativeUrl.replace(/^\/api/, "");
+    const { data } = await api.get(path, { responseType: "blob" });
+    return data as unknown as Blob;
+  },
   sendMessage: async (
     id: string,
-    body: SendSupportMessageDto,
+    input: SendMessageInput,
   ): Promise<SupportMessageDto> => {
     const { data } = await api.post<SupportMessageDto>(
       `/support/agent/conversations/${id}/messages`,
-      body,
+      toRequestBody(input),
     );
     return data;
   },
diff --git a/apps/edr-freight-web/backoffice/src/features/support/useAttachmentDraft.ts b/apps/edr-freight-web/backoffice/src/features/support/useAttachmentDraft.ts
new file mode 100644
index 000000000..160637c9d
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/features/support/useAttachmentDraft.ts
@@ -0,0 +1,130 @@
+import {
+  isSupportAttachmentImage,
+  SUPPORT_ATTACHMENT_MAX_BYTES,
+  SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+  isSupportAttachmentAllowed,
+} from "@edr/types";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** A file staged in the composer, not yet sent. */
+export interface PendingAttachment {
+  /** Local-only id; the server id doesn't exist until the message is sent. */
+  id: string;
+  file: File;
+  /** Object URL, images only. Revoked when the entry goes away. */
+  previewUrl?: string;
+}
+
+let nextId = 0;
+
+/**
+ * Staging area for files being attached to a message.
+ *
+ * Files are held client-side until send, then posted alongside the text in one
+ * multipart request — there's no upload-then-reference step, so nothing to
+ * garbage-collect if the agent changes their mind.
+ *
+ * Object URLs for image previews are revoked on removal and unmount; without
+ * that, pasting screenshots into a long-lived chat page leaks the full bytes of
+ * every image for the life of the tab.
+ */
+export function useAttachmentDraft(onReject?: (reason: string) => void) {
+  const [attachments, setAttachments] = useState<PendingAttachment[]>([]);
+  const rejectRef = useRef(onReject);
+  rejectRef.current = onReject;
+
+  // Read from a ref in the unmount cleanup so it doesn't re-run (and revoke
+  // still-live URLs) on every change to the list.
+  const attachmentsRef = useRef(attachments);
+  attachmentsRef.current = attachments;
+  useEffect(
+    () => () => {
+      for (const a of attachmentsRef.current) {
+        if (a.previewUrl) URL.revokeObjectURL(a.previewUrl);
+      }
+    },
+    [],
+  );
+
+  const add = useCallback((files: File[]) => {
+    if (files.length === 0) return;
+    setAttachments((current) => {
+      const accepted: PendingAttachment[] = [];
+      for (const file of files) {
+        if (
+          current.length + accepted.length >=
+          SUPPORT_ATTACHMENT_MAX_PER_MESSAGE
+        ) {
+          rejectRef.current?.(
+            `Up to ${SUPPORT_ATTACHMENT_MAX_PER_MESSAGE} files per message.`,
+          );
+          break;
+        }
+        if (!isSupportAttachmentAllowed(file.type)) {
+          rejectRef.current?.(`${file.name}: that file type isn't supported.`);
+          continue;
+        }
+        if (file.size > SUPPORT_ATTACHMENT_MAX_BYTES) {
+          rejectRef.current?.(
+            `${file.name} is over the ${
+              SUPPORT_ATTACHMENT_MAX_BYTES / (1024 * 1024)
+            }MB limit.`,
+          );
+          continue;
+        }
+        accepted.push({
+          id: `pending-${nextId++}`,
+          file,
+          previewUrl: isSupportAttachmentImage(file.type)
+            ? URL.createObjectURL(file)
+            : undefined,
+        });
+      }
+      return accepted.length ? [...current, ...accepted] : current;
+    });
+  }, []);
+
+  const remove = useCallback((id: string) => {
+    setAttachments((current) => {
+      const target = current.find((a) => a.id === id);
+      if (target?.previewUrl) URL.revokeObjectURL(target.previewUrl);
+      return current.filter((a) => a.id !== id);
+    });
+  }, []);
+
+  const clear = useCallback(() => {
+    setAttachments((current) => {
+      for (const a of current) {
+        if (a.previewUrl) URL.revokeObjectURL(a.previewUrl);
+      }
+      return [];
+    });
+  }, []);
+
+  /**
+   * Pull files off a paste. Returns true if anything was taken, so the caller
+   * can suppress the default paste — otherwise pasting a screenshot also drops
+   * its filename (or nothing) into the textarea.
+   *
+   * Copying an image in most apps puts BOTH the bitmap and some text/html on the
+   * clipboard, so check for files first and only then let the text through.
+   */
+  const addFromPaste = useCallback(
+    (clipboard: DataTransfer | null): boolean => {
+      const files = Array.from(clipboard?.files ?? []);
+      if (files.length === 0) return false;
+      add(files);
+      return true;
+    },
+    [add],
+  );
+
+  return {
+    attachments,
+    files: attachments.map((a) => a.file),
+    add,
+    addFromPaste,
+    remove,
+    clear,
+  };
+}
diff --git a/apps/edr-freight-web/backoffice/src/features/support/useAttachmentObjectUrl.ts b/apps/edr-freight-web/backoffice/src/features/support/useAttachmentObjectUrl.ts
new file mode 100644
index 000000000..9253b7690
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/features/support/useAttachmentObjectUrl.ts
@@ -0,0 +1,80 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { supportApi } from "./supportApi";
+
+/**
+ * Blob object URL for an attachment, or `undefined` while it loads / on failure.
+ *
+ * Chat attachments cannot be rendered with a direct `<img src={a.url}>`. The API
+ * guard takes the bearer token from the `Authorization` header and has no cookie
+ * fallback, and an `<img>` request cannot carry that header — a direct src is an
+ * unavoidable 401. So the bytes are fetched through the authenticated client and
+ * handed to the browser as an object URL, the same way booking documents are
+ * downloaded.
+ *
+ * The URL is revoked on unmount and whenever the attachment changes, so a thread
+ * scrolled through hundreds of images doesn't pin all of them in memory.
+ */
+export function useAttachmentObjectUrl(relativeUrl: string): {
+  src?: string;
+  failed: boolean;
+} {
+  const [src, setSrc] = useState<string>();
+  const [failed, setFailed] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    let created: string | undefined;
+
+    setSrc(undefined);
+    setFailed(false);
+
+    supportApi
+      .fetchAttachment(relativeUrl)
+      .then((blob) => {
+        // The component may have unmounted mid-flight; creating a URL then would
+        // leak it, since the cleanup below has already run.
+        if (cancelled) return;
+        created = URL.createObjectURL(blob);
+        setSrc(created);
+      })
+      .catch(() => {
+        if (!cancelled) setFailed(true);
+      });
+
+    return () => {
+      cancelled = true;
+      if (created) URL.revokeObjectURL(created);
+    };
+  }, [relativeUrl]);
+
+  return { src, failed };
+}
+
+/**
+ * On-demand variant for files that aren't previewed inline (documents): fetch
+ * only when the user actually opens one, rather than pulling every attachment in
+ * the thread down just to render a filename row.
+ *
+ * Holds a single slot — opening another file revokes the previous URL, as does
+ * unmounting.
+ */
+export function useLazyAttachmentObjectUrl(): (
+  relativeUrl: string,
+) => Promise<string> {
+  const current = useRef<string>();
+
+  useEffect(
+    () => () => {
+      if (current.current) URL.revokeObjectURL(current.current);
+    },
+    [],
+  );
+
+  return useCallback(async (relativeUrl: string) => {
+    const blob = await supportApi.fetchAttachment(relativeUrl);
+    if (current.current) URL.revokeObjectURL(current.current);
+    current.current = URL.createObjectURL(blob);
+    return current.current;
+  }, []);
+}
diff --git a/apps/edr-freight-web/backoffice/src/features/support/useSupport.ts b/apps/edr-freight-web/backoffice/src/features/support/useSupport.ts
index da152191e..6a582321c 100644
--- a/apps/edr-freight-web/backoffice/src/features/support/useSupport.ts
+++ b/apps/edr-freight-web/backoffice/src/features/support/useSupport.ts
@@ -1,6 +1,23 @@
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type {
+  SupportConversationDto,
+  SupportMessageDto,
+  SupportMessageListResult,
+} from "@edr/types";
+import { useMemo } from "react";
+import {
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type InfiniteData,
+  type QueryClient,
+} from "@tanstack/react-query";
 
-import { supportApi, type ListConversationsParams } from "./supportApi";
+import {
+  supportApi,
+  type ListConversationsParams,
+  type SendMessageInput,
+} from "./supportApi";
 
 export const SUPPORT_KEY = ["support"] as const;
 export const SUPPORT_CONVERSATIONS_KEY = ["support", "conversations"] as const;
@@ -8,20 +25,145 @@ export const SUPPORT_UNREAD_KEY = ["support", "unread"] as const;
 export const supportMessagesKey = (id: string) =>
   ["support", "messages", id] as const;
 
-/** Shared inbox: every thread, filterable by unread + company-name search. */
+/** Threads per page in the inbox. */
+const CONVERSATIONS_PAGE_SIZE = 20;
+/** Messages per page in a thread. */
+const MESSAGES_PAGE_SIZE = 30;
+
+/**
+ * Shared inbox: every thread, filterable by unread + company-name search.
+ *
+ * Pages on scroll. This previously asked for `limit: 100` and rendered whatever
+ * came back — which silently truncated the inbox at the server's own max of 100
+ * with no way to reach the rest.
+ */
 export function useConversations(params: ListConversationsParams = {}) {
-  return useQuery({
+  const query = useInfiniteQuery({
     queryKey: [...SUPPORT_CONVERSATIONS_KEY, params],
-    queryFn: () => supportApi.listConversations({ limit: 100, ...params }),
+    queryFn: ({ pageParam }) =>
+      supportApi.listConversations({
+        ...params,
+        page: pageParam,
+        limit: CONVERSATIONS_PAGE_SIZE,
+      }),
+    initialPageParam: 1,
+    getNextPageParam: (lastPage, allPages) => {
+      const loaded = allPages.reduce((n, page) => n + page.items.length, 0);
+      return loaded < lastPage.count ? allPages.length + 1 : undefined;
+    },
   });
+
+  /**
+   * Flatten for rendering, keeping the page-level fields (count/unreadCount)
+   * from the newest fetch so badges don't go stale as more pages load.
+   *
+   * De-duplicated by id because this list pages by OFFSET over a sort key that
+   * moves: a thread jumps to rank 1 the moment it gets a message, shifting
+   * everything down, so a row already shown on page 1 can be served again on
+   * page 2 — and React would then see two children with the same key. The
+   * conversations invalidate that rides along with every such event heals the
+   * ordering a beat later; this just stops the intervening render from breaking.
+   *
+   * Keyset wouldn't help here, unlike the message list: the sort key itself
+   * mutates, so no cursor over it is stable either.
+   */
+  const items = useMemo(() => {
+    const seen = new Set<string>();
+    const flat: SupportConversationDto[] = [];
+    for (const page of query.data?.pages ?? []) {
+      for (const conversation of page.items) {
+        if (seen.has(conversation.id)) continue;
+        seen.add(conversation.id);
+        flat.push(conversation);
+      }
+    }
+    return flat;
+  }, [query.data]);
+
+  return {
+    ...query,
+    items,
+    count: query.data?.pages[0]?.count ?? 0,
+    unreadCount: query.data?.pages[0]?.unreadCount ?? 0,
+  };
 }
 
+/**
+ * A thread's messages, paged backwards from newest.
+ *
+ * react-query's "next page" is *older* history here, so `pages` runs
+ * newest-block-first and has to be reversed to render top-to-bottom in time
+ * order. Cursor-based rather than offset so a message arriving mid-scroll
+ * doesn't shift the pages already loaded.
+ */
 export function useMessages(conversationId: string | null) {
-  return useQuery({
+  const query = useInfiniteQuery({
     queryKey: supportMessagesKey(conversationId ?? ""),
-    queryFn: () => supportApi.listMessages(conversationId as string),
+    queryFn: ({ pageParam }) =>
+      supportApi.listMessages(conversationId as string, {
+        before: pageParam,
+        limit: MESSAGES_PAGE_SIZE,
+      }),
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
     enabled: !!conversationId,
   });
+
+  const messages = useMemo(
+    () => [...(query.data?.pages ?? [])].reverse().flatMap((p) => p.items),
+    [query.data],
+  );
+
+  // Exposed so the view can tell a prepended history page from a message
+  // appended at the bottom — `messages` changing says nothing about which.
+  return { ...query, messages, pageCount: query.data?.pages.length ?? 0 };
+}
+
+/**
+ * Splice a newly-arrived message into a cached thread.
+ *
+ * Deliberately not `invalidateQueries`: that refetches *every* page the agent
+ * has scrolled back through, so the cost of each inbound message would grow with
+ * how far they've read. Page 0 is the newest block and its items are oldest-first
+ * within the block, so the new message belongs on its end.
+ *
+ * No-ops when the thread isn't cached — nothing is rendering it, and seeding a
+ * partial cache here would leave a thread whose "first page" is one message and
+ * whose `nextCursor` is missing.
+ */
+/**
+ * Why this reports an outcome rather than a boolean: the two ways it can decline
+ * to append need opposite handling. A duplicate is the sender's own echo and must
+ * be ignored — refetching there would undo the whole point. "Uncached" means the
+ * thread's first page is still in flight and may have been read on the server
+ * *before* this message existed, so dropping it silently would lose it until
+ * something else happened to refetch; the caller refetches instead. That's cheap
+ * precisely because nothing is loaded yet.
+ */
+export type AppendOutcome = "appended" | "duplicate" | "uncached";
+
+export function appendMessageToCache(
+  qc: QueryClient,
+  message: SupportMessageDto,
+): AppendOutcome {
+  let outcome: AppendOutcome = "uncached";
+  qc.setQueryData<InfiniteData<SupportMessageListResult>>(
+    supportMessagesKey(message.conversationId),
+    (current) => {
+      if (!current?.pages.length) return current;
+      const [newest, ...rest] = current.pages;
+      if (newest.items.some((m) => m.id === message.id)) {
+        outcome = "duplicate";
+        return current;
+      }
+      outcome = "appended";
+      return {
+        ...current,
+        pages: [{ ...newest, items: [...newest.items, message] }, ...rest],
+      };
+    },
+  );
+  return outcome;
 }
 
 export function useSupportUnreadCount(enabled = true) {
@@ -36,10 +178,13 @@ export function useSupportUnreadCount(enabled = true) {
 export function useSendMessage(conversationId: string) {
   const qc = useQueryClient();
   return useMutation({
-    mutationFn: (body: string) =>
-      supportApi.sendMessage(conversationId, { body }),
+    mutationFn: (input: SendMessageInput) =>
+      supportApi.sendMessage(conversationId, input),
+    // The gateway echoes our own message back over the socket, which appends it
+    // to the cache — so don't invalidate the thread here or every send would
+    // refetch every page the agent has scrolled through. The conversation list
+    // still needs a refresh for its last-message preview and ordering.
     onSuccess: () => {
-      qc.invalidateQueries({ queryKey: supportMessagesKey(conversationId) });
       qc.invalidateQueries({ queryKey: SUPPORT_CONVERSATIONS_KEY });
     },
   });
diff --git a/apps/edr-freight-web/backoffice/src/features/support/useSupportSocket.ts b/apps/edr-freight-web/backoffice/src/features/support/useSupportSocket.ts
index 574ef7b5c..b52d2c780 100644
--- a/apps/edr-freight-web/backoffice/src/features/support/useSupportSocket.ts
+++ b/apps/edr-freight-web/backoffice/src/features/support/useSupportSocket.ts
@@ -12,6 +12,7 @@ import { AUTH_TOKEN_COOKIE, getCookie } from "@/auth/cookies";
 import { API_BASE_URL } from "@/constants/apiConfig";
 
 import {
+  appendMessageToCache,
   SUPPORT_CONVERSATIONS_KEY,
   SUPPORT_UNREAD_KEY,
   supportMessagesKey,
@@ -45,14 +46,25 @@ export function useSupportSocket(
       withCredentials: true,
     });
 
-    socket.on(SUPPORT_CHAT_WS_EVENTS.MESSAGE_NEW, (event: SupportMessageEvent) => {
-      qc.invalidateQueries({
-        queryKey: supportMessagesKey(event.message.conversationId),
-      });
-      qc.invalidateQueries({ queryKey: SUPPORT_CONVERSATIONS_KEY });
-      qc.invalidateQueries({ queryKey: SUPPORT_UNREAD_KEY });
-      onMessageRef.current?.(event);
-    });
+    socket.on(
+      SUPPORT_CHAT_WS_EVENTS.MESSAGE_NEW,
+      (event: SupportMessageEvent) => {
+        // Append rather than invalidate: the thread is paginated, and invalidating
+        // it would refetch every page the agent has scrolled back through on every
+        // single inbound message.
+        if (appendMessageToCache(qc, event.message) === "uncached") {
+          // The thread's first page is still loading and may have been read before
+          // this message existed — without this it would go missing until some
+          // unrelated refetch. Cheap: there are no pages to re-fetch yet.
+          qc.invalidateQueries({
+            queryKey: supportMessagesKey(event.message.conversationId),
+          });
+        }
+        qc.invalidateQueries({ queryKey: SUPPORT_CONVERSATIONS_KEY });
+        qc.invalidateQueries({ queryKey: SUPPORT_UNREAD_KEY });
+        onMessageRef.current?.(event);
+      },
+    );
 
     socket.on(
       SUPPORT_CHAT_WS_EVENTS.CONVERSATION_UPDATED,
diff --git a/apps/edr-freight-web/backoffice/src/pages/support/SupportInboxPage.tsx b/apps/edr-freight-web/backoffice/src/pages/support/SupportInboxPage.tsx
index 861b3bee7..6b2b5df2e 100644
--- a/apps/edr-freight-web/backoffice/src/pages/support/SupportInboxPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/support/SupportInboxPage.tsx
@@ -1,8 +1,11 @@
 import {
+  SUPPORT_ATTACHMENT_ACCEPT,
   SupportAuthorRole,
+  type SupportAttachmentDto,
   type SupportConversationDto,
   type SupportMessageDto,
 } from "@edr/types";
+import { useFileViewer } from "@edr/ui-common";
 import {
   ActionIcon,
   Avatar,
@@ -23,10 +26,22 @@ import {
   ThemeIcon,
 } from "@mantine/core";
 import { useQuery } from "@tanstack/react-query";
-import { Building2, Headset, Plus, Search, Send, User } from "lucide-react";
-import { useEffect, useMemo, useRef, useState } from "react";
+import {
+  Building2,
+  Headset,
+  Paperclip,
+  Plus,
+  Search,
+  Send,
+  User,
+} from "lucide-react";
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import toast from "react-hot-toast";
 
+import { useLazyAttachmentObjectUrl } from "@/features/support/useAttachmentObjectUrl";
+import { AttachmentDraftBar } from "@/features/support/AttachmentDraftBar";
+import { MessageAttachments } from "@/features/support/MessageAttachments";
+import { useAttachmentDraft } from "@/features/support/useAttachmentDraft";
 import {
   useConversations,
   useMarkConversationRead,
@@ -39,6 +54,9 @@ import { customersService } from "@/services/customers.service";
 
 type ReadFilter = "ALL" | "UNREAD";
 
+/** Distance from an edge (px) that counts as "at" it. */
+const SCROLL_EDGE_SLOP = 120;
+
 function formatTime(iso?: string | null): string {
   if (!iso) return "";
   const d = new Date(iso);
@@ -54,12 +72,24 @@ export default function SupportInboxPage() {
   const [search, setSearch] = useState("");
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [pickerOpen, setPickerOpen] = useState(false);
+  const inboxViewport = useRef<HTMLDivElement>(null);
+  /**
+   * The thread just opened from the company picker.
+   *
+   * Selection resolves against the *loaded* pages, and a company picked from the
+   * modal may well have a thread that sits far enough down the list to not be
+   * loaded yet — in which case the lookup below would find nothing and the pane
+   * would sit blank. Hold onto the conversation the server handed back so the
+   * pane can open immediately, regardless of where it falls in the inbox.
+   */
+  const [startedConversation, setStartedConversation] =
+    useState<SupportConversationDto | null>(null);
 
-  const { data, isLoading } = useConversations({
-    search,
-    unreadOnly: readFilter === "UNREAD",
-  });
-  const items = data?.items ?? [];
+  const { items, isLoading, hasNextPage, isFetchingNextPage, fetchNextPage } =
+    useConversations({
+      search,
+      unreadOnly: readFilter === "UNREAD",
+    });
 
   useSupportSocket(true, (event) => {
     if (event.message.authorRole === SupportAuthorRole.CUSTOMER) {
@@ -70,10 +100,13 @@ export default function SupportInboxPage() {
     }
   });
 
-  const selected = useMemo(
-    () => items.find((c) => c.id === selectedId) ?? null,
-    [items, selectedId],
-  );
+  // Prefer the live row from the list (its unread count and last message stay
+  // current); fall back to the picker's copy while its page is still unloaded.
+  const selected = useMemo(() => {
+    const fromList = items.find((c) => c.id === selectedId);
+    if (fromList) return fromList;
+    return startedConversation?.id === selectedId ? startedConversation : null;
+  }, [items, selectedId, startedConversation]);
 
   return (
     <Box p="md">
@@ -109,7 +142,10 @@ export default function SupportInboxPage() {
             borderRight: "1px solid var(--mantine-color-gray-2)",
           }}
         >
-          <Box p="sm" style={{ borderBottom: "1px solid var(--mantine-color-gray-2)" }}>
+          <Box
+            p="sm"
+            style={{ borderBottom: "1px solid var(--mantine-color-gray-2)" }}
+          >
             <Button
               fullWidth
               color="edr-green"
@@ -140,24 +176,47 @@ export default function SupportInboxPage() {
               ]}
             />
           </Box>
-          <ScrollArea style={{ flex: 1 }} type="hover">
+          <ScrollArea
+            style={{ flex: 1 }}
+            type="hover"
+            // Pull the next page in as the agent nears the end of the list.
+            // Previously the hook asked for 100 rows and stopped there, so any
+            // company past the hundredth was simply unreachable.
+            onScrollPositionChange={({ y }) => {
+              const el = inboxViewport.current;
+              if (!el || !hasNextPage || isFetchingNextPage) return;
+              if (el.scrollHeight - y - el.clientHeight < SCROLL_EDGE_SLOP) {
+                fetchNextPage();
+              }
+            }}
+            viewportRef={inboxViewport}
+          >
             {isLoading ? (
               <Group justify="center" p="xl">
                 <Loader size="sm" color="edr-green" />
               </Group>
             ) : items.length === 0 ? (
               <Text c="dimmed" size="sm" ta="center" p="xl">
-                {readFilter === "UNREAD" ? "Nothing unread." : "No conversations."}
+                {readFilter === "UNREAD"
+                  ? "Nothing unread."
+                  : "No conversations."}
               </Text>
             ) : (
-              items.map((c) => (
-                <InboxRow
-                  key={c.id}
-                  c={c}
-                  active={c.id === selectedId}
-                  onClick={() => setSelectedId(c.id)}
-                />
-              ))
+              <>
+                {items.map((c) => (
+                  <InboxRow
+                    key={c.id}
+                    c={c}
+                    active={c.id === selectedId}
+                    onClick={() => setSelectedId(c.id)}
+                  />
+                ))}
+                {isFetchingNextPage && (
+                  <Group justify="center" p="sm">
+                    <Loader size="xs" color="edr-green" />
+                  </Group>
+                )}
+              </>
             )}
           </ScrollArea>
         </Stack>
@@ -168,7 +227,12 @@ export default function SupportInboxPage() {
             <ConversationThread conversation={selected} />
           ) : (
             <Stack align="center" justify="center" h="100%" c="dimmed" gap="xs">
-              <ThemeIcon variant="light" color="edr-green" radius="xl" size={56}>
+              <ThemeIcon
+                variant="light"
+                color="edr-green"
+                radius="xl"
+                size={56}
+              >
                 <Headset size={28} />
               </ThemeIcon>
               <Text size="sm">Select a conversation, or start a new chat.</Text>
@@ -180,8 +244,9 @@ export default function SupportInboxPage() {
       <CompanyPicker
         opened={pickerOpen}
         onClose={() => setPickerOpen(false)}
-        onStarted={(id) => {
-          setSelectedId(id);
+        onStarted={(conversation) => {
+          setStartedConversation(conversation);
+          setSelectedId(conversation.id);
           setPickerOpen(false);
         }}
       />
@@ -200,7 +265,7 @@ function CompanyPicker({
 }: {
   opened: boolean;
   onClose: () => void;
-  onStarted: (conversationId: string) => void;
+  onStarted: (conversation: SupportConversationDto) => void;
 }) {
   const [companyId, setCompanyId] = useState<string | null>(null);
   const start = useStartConversation();
@@ -224,15 +289,23 @@ function CompanyPicker({
     if (!companyId) return;
     const conversation = await start.mutateAsync(companyId);
     setCompanyId(null);
-    onStarted(conversation.id);
+    onStarted(conversation);
   };
 
   return (
-    <Modal opened={opened} onClose={onClose} title="Start a chat" radius="md" centered>
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      title="Start a chat"
+      radius="md"
+      centered
+    >
       <Stack gap="md">
         <Select
           label="Customer"
-          placeholder={isLoading ? "Loading companies…" : "Search for a company"}
+          placeholder={
+            isLoading ? "Loading companies…" : "Search for a company"
+          }
           data={options}
           value={companyId}
           onChange={setCompanyId}
@@ -319,26 +392,133 @@ function ConversationThread({
 }: {
   conversation: SupportConversationDto;
 }) {
-  const { data: messages, isLoading } = useMessages(conversation.id);
+  const {
+    messages,
+    pageCount,
+    isLoading,
+    hasNextPage,
+    isFetchingNextPage,
+    fetchNextPage,
+  } = useMessages(conversation.id);
   const send = useSendMessage(conversation.id);
   const markRead = useMarkConversationRead();
   const [draft, setDraft] = useState("");
+  const [dragging, setDragging] = useState(false);
   const viewport = useRef<HTMLDivElement>(null);
+  const fileInput = useRef<HTMLInputElement>(null);
+  const { view, viewer } = useFileViewer();
+  const attach = useAttachmentDraft((reason) => toast.error(reason));
+
+  /**
+   * Scroll height captured just before an older page was requested, tagged with
+   * the page count at that moment.
+   *
+   * The page count is what makes this safe. Keyed on presence alone, a message
+   * arriving over the socket while history was still in flight would consume the
+   * snapshot on a one-bubble append, and the real 30-message prepend would then
+   * land with nothing to correct against — throwing the reader exactly as far as
+   * this exists to prevent. Comparing counts means only an actual new page can
+   * claim it.
+   */
+  const pendingRestore = useRef<{ height: number; atPageCount: number } | null>(
+    null,
+  );
+  /** Whether the agent is parked at the bottom and wants to follow new messages. */
+  const stick = useRef(true);
+  /** Which thread the refs above describe; a switch resets them. */
+  const anchoredThread = useRef(conversation.id);
+
+  const messageCount = messages.length;
 
   useEffect(() => {
     markRead.mutate(conversation.id);
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [conversation.id, messages?.length]);
+  }, [conversation.id, messageCount]);
 
-  useEffect(() => {
-    viewport.current?.scrollTo({ top: viewport.current.scrollHeight });
-  }, [messages?.length, conversation.id]);
+  /**
+   * Keep the viewport sensible as the list changes underneath it.
+   *
+   * Two different things change `messages`, and they want opposite behaviour: a
+   * new message at the bottom should follow (if the agent is already there),
+   * while an older page prepended at the top must NOT move what they're reading.
+   * Layout effect, not effect — this must run before paint or the prepend
+   * visibly jumps.
+   */
+  useLayoutEffect(() => {
+    const el = viewport.current;
+    if (!el) return;
+
+    // Thread switch: start a fresh read at the bottom and drop the previous
+    // thread's anchoring state.
+    if (anchoredThread.current !== conversation.id) {
+      anchoredThread.current = conversation.id;
+      pendingRestore.current = null;
+      stick.current = true;
+      el.scrollTo({ top: el.scrollHeight });
+      return;
+    }
+
+    const restore = pendingRestore.current;
+    if (restore && pageCount > restore.atPageCount) {
+      // An older page went in above: push the scroll down by exactly the height
+      // that was added, so the same message stays under the cursor.
+      el.scrollTop += el.scrollHeight - restore.height;
+      pendingRestore.current = null;
+      return;
+    }
+    if (stick.current) el.scrollTo({ top: el.scrollHeight });
+  }, [messages, pageCount, conversation.id]);
+
+  const onScroll = ({ y }: { y: number }) => {
+    const el = viewport.current;
+    if (!el) return;
+    stick.current = el.scrollHeight - y - el.clientHeight < SCROLL_EDGE_SLOP;
+    if (y < SCROLL_EDGE_SLOP && hasNextPage && !isFetchingNextPage) {
+      // A failed fetch leaves this set, which is harmless: the list didn't
+      // change, so the height is still accurate for the retry, and the count
+      // tag stops it being mistaken for a landed page in the meantime.
+      pendingRestore.current = {
+        height: el.scrollHeight,
+        atPageCount: pageCount,
+      };
+      fetchNextPage();
+    }
+  };
 
   const submit = async () => {
     const body = draft.trim();
-    if (!body) return;
+    if (!body && attach.attachments.length === 0) return;
+    const files = attach.files;
+    // Clear optimistically so the composer feels instant; on failure the text is
+    // restored below rather than silently lost.
     setDraft("");
-    await send.mutateAsync(body);
+    attach.clear();
+    stick.current = true;
+    try {
+      await send.mutateAsync({ body: body || undefined, attachments: files });
+    } catch (error) {
+      setDraft(body);
+      toast.error(
+        error instanceof Error ? error.message : "Couldn't send that message.",
+      );
+    }
+  };
+
+  const loadAttachment = useLazyAttachmentObjectUrl();
+
+  // Images already hold their bytes as an object URL from rendering the
+  // thumbnail, so reuse it rather than fetching the same file twice.
+  const openAttachment = (a: SupportAttachmentDto, src: string) =>
+    view({ name: a.name, url: src, mimeType: a.mimeType });
+
+  // Documents aren't fetched until opened.
+  const openFile = async (a: SupportAttachmentDto) => {
+    try {
+      const src = await loadAttachment(a.url);
+      view({ name: a.name, url: src, mimeType: a.mimeType });
+    } catch {
+      toast.error(`Couldn't open ${a.name}.`);
+    }
   };
 
   return (
@@ -361,36 +541,108 @@ function ConversationThread({
       </Group>
 
       {/* Messages */}
-      <ScrollArea style={{ flex: 1 }} viewportRef={viewport} type="hover">
+      <ScrollArea
+        style={{ flex: 1 }}
+        viewportRef={viewport}
+        type="hover"
+        onScrollPositionChange={onScroll}
+      >
         {isLoading ? (
           <Group justify="center" p="xl">
             <Loader size="sm" color="edr-green" />
           </Group>
-        ) : (messages ?? []).length === 0 ? (
+        ) : messages.length === 0 ? (
           <Text c="dimmed" size="sm" ta="center" p="xl">
             No messages yet — say hello.
           </Text>
         ) : (
           <Stack gap="sm" p="md">
-            {(messages ?? []).map((m) => (
-              <AgentBubble key={m.id} m={m} />
+            {isFetchingNextPage && (
+              <Group justify="center" py="xs">
+                <Loader size="xs" color="edr-green" />
+              </Group>
+            )}
+            {!hasNextPage && (
+              <Text size="10px" c="dimmed" ta="center">
+                Start of conversation
+              </Text>
+            )}
+            {messages.map((m) => (
+              <AgentBubble
+                key={m.id}
+                m={m}
+                onView={openAttachment}
+                onOpenFile={openFile}
+              />
             ))}
           </Stack>
         )}
       </ScrollArea>
 
       {/* Composer */}
-      <Box p="sm" style={{ borderTop: "1px solid var(--mantine-color-gray-2)" }}>
+      <Box
+        p="sm"
+        style={{
+          borderTop: "1px solid var(--mantine-color-gray-2)",
+          background: dragging ? "var(--mantine-color-edr-green-0)" : undefined,
+          outline: dragging
+            ? "2px dashed var(--mantine-color-edr-green-6)"
+            : undefined,
+          outlineOffset: -4,
+        }}
+        onDragOver={(e) => {
+          e.preventDefault();
+          setDragging(true);
+        }}
+        onDragLeave={() => setDragging(false)}
+        onDrop={(e) => {
+          e.preventDefault();
+          setDragging(false);
+          attach.add(Array.from(e.dataTransfer.files));
+        }}
+      >
+        <AttachmentDraftBar
+          attachments={attach.attachments}
+          onRemove={attach.remove}
+        />
         <Group gap="xs" align="flex-end" wrap="nowrap">
+          <input
+            ref={fileInput}
+            type="file"
+            multiple
+            accept={SUPPORT_ATTACHMENT_ACCEPT}
+            hidden
+            onChange={(e) => {
+              attach.add(Array.from(e.currentTarget.files ?? []));
+              // Reset so picking the same file twice in a row still fires change.
+              e.currentTarget.value = "";
+            }}
+          />
+          <ActionIcon
+            size={38}
+            radius="md"
+            variant="subtle"
+            color="gray"
+            aria-label="Attach files"
+            onClick={() => fileInput.current?.click()}
+          >
+            <Paperclip size={18} />
+          </ActionIcon>
           <Textarea
             value={draft}
             onChange={(e) => setDraft(e.currentTarget.value)}
-            placeholder="Type your message…  (Enter to send, Shift+Enter for newline)"
+            placeholder="Type a message, or paste an image…  (Enter to send, Shift+Enter for newline)"
             autosize
             minRows={1}
             maxRows={5}
             radius="md"
             style={{ flex: 1 }}
+            // Screenshots land on the clipboard as files. Take them and suppress
+            // the default, which would otherwise also paste the image's name (or
+            // nothing) as text.
+            onPaste={(e) => {
+              if (attach.addFromPaste(e.clipboardData)) e.preventDefault();
+            }}
             onKeyDown={(e) => {
               if (e.key === "Enter" && !e.shiftKey) {
                 e.preventDefault();
@@ -404,18 +656,27 @@ function ConversationThread({
             color="edr-green"
             variant="filled"
             loading={send.isPending}
-            disabled={!draft.trim()}
+            disabled={!draft.trim() && attach.attachments.length === 0}
             onClick={submit}
           >
             <Send size={18} />
           </ActionIcon>
         </Group>
       </Box>
+      {viewer}
     </Stack>
   );
 }
 
-function AgentBubble({ m }: { m: SupportMessageDto }) {
+function AgentBubble({
+  m,
+  onView,
+  onOpenFile,
+}: {
+  m: SupportMessageDto;
+  onView: (a: SupportAttachmentDto, src: string) => void;
+  onOpenFile: (a: SupportAttachmentDto) => void;
+}) {
   const mine = m.authorRole === SupportAuthorRole.AGENT;
   return (
     <Group
@@ -430,7 +691,13 @@ function AgentBubble({ m }: { m: SupportMessageDto }) {
         </Avatar>
       )}
       <Box style={{ maxWidth: "70%" }}>
-        <Text size="xs" c="dimmed" mb={2} ml={mine ? 0 : 4} ta={mine ? "right" : "left"}>
+        <Text
+          size="xs"
+          c="dimmed"
+          mb={2}
+          ml={mine ? 0 : 4}
+          ta={mine ? "right" : "left"}
+        >
           {mine ? m.authorName || "You" : m.authorName || "Customer"}
         </Text>
         <Paper
@@ -446,9 +713,20 @@ function AgentBubble({ m }: { m: SupportMessageDto }) {
             borderBottomLeftRadius: mine ? undefined : 4,
           }}
         >
-          <Text size="sm" style={{ whiteSpace: "pre-wrap", wordBreak: "break-word" }}>
-            {m.body}
-          </Text>
+          {m.body && (
+            <Text
+              size="sm"
+              style={{ whiteSpace: "pre-wrap", wordBreak: "break-word" }}
+            >
+              {m.body}
+            </Text>
+          )}
+          <MessageAttachments
+            attachments={m.attachments}
+            mine={mine}
+            onView={onView}
+            onOpenFile={onOpenFile}
+          />
         </Paper>
         <Text size="10px" c="dimmed" mt={2} ta={mine ? "right" : "left"}>
           {formatTime(m.createdAt)}
diff --git a/apps/edr-freight-web/portal/src/features/support/AttachmentDraftBar.tsx b/apps/edr-freight-web/portal/src/features/support/AttachmentDraftBar.tsx
new file mode 100644
index 000000000..4c6860a97
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/features/support/AttachmentDraftBar.tsx
@@ -0,0 +1,80 @@
+import { ActionIcon, Box, Group, Image, Paper, Text } from "@mantine/core";
+import { FileText, X } from "lucide-react";
+
+import { formatBytes } from "./MessageAttachments";
+import type { PendingAttachment } from "./useAttachmentDraft";
+
+/**
+ * The staged-files strip above the composer. Shows what will be sent and lets
+ * the customer drop any of it before hitting send.
+ */
+export function AttachmentDraftBar({
+  attachments,
+  onRemove,
+}: {
+  attachments: PendingAttachment[];
+  onRemove: (id: string) => void;
+}) {
+  if (attachments.length === 0) return null;
+
+  return (
+    <Group gap="xs" mb="xs" wrap="wrap">
+      {attachments.map((a) => (
+        <Paper
+          key={a.id}
+          withBorder
+          radius="md"
+          p={4}
+          style={{ position: "relative" }}
+        >
+          <Group gap={6} wrap="nowrap" pr={16}>
+            {a.previewUrl ? (
+              <Image
+                src={a.previewUrl}
+                alt={a.file.name}
+                w={32}
+                h={32}
+                radius="sm"
+                fit="cover"
+              />
+            ) : (
+              <Box
+                w={32}
+                h={32}
+                style={{
+                  display: "grid",
+                  placeItems: "center",
+                  background: "var(--mantine-color-gray-1)",
+                  borderRadius: 4,
+                }}
+              >
+                <FileText size={14} />
+              </Box>
+            )}
+            {/* Narrower name cap than the backoffice so two chips still fit
+                across the widget's 384px column. */}
+            <Box style={{ minWidth: 0, maxWidth: 92 }}>
+              <Text size="xs" fw={600} truncate>
+                {a.file.name}
+              </Text>
+              <Text size="10px" c="dimmed">
+                {formatBytes(a.file.size)}
+              </Text>
+            </Box>
+          </Group>
+          <ActionIcon
+            size="xs"
+            radius="xl"
+            color="gray"
+            variant="filled"
+            aria-label={`Remove ${a.file.name}`}
+            onClick={() => onRemove(a.id)}
+            style={{ position: "absolute", top: -6, right: -6 }}
+          >
+            <X size={10} />
+          </ActionIcon>
+        </Paper>
+      ))}
+    </Group>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/features/support/MessageAttachments.tsx b/apps/edr-freight-web/portal/src/features/support/MessageAttachments.tsx
new file mode 100644
index 000000000..13c7dece6
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/features/support/MessageAttachments.tsx
@@ -0,0 +1,123 @@
+import {
+  isSupportAttachmentImage,
+  type SupportAttachmentDto,
+} from "@edr/types";
+import { Box, Group, Image, Loader, Paper, Stack, Text } from "@mantine/core";
+import { FileText, ImageOff } from "lucide-react";
+
+import { useAttachmentObjectUrl } from "./useAttachmentObjectUrl";
+
+/** Human-readable size — kept coarse; nobody needs bytes in a chat bubble. */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** Thumbnail box size — the widget is a narrow column, so keep it modest. */
+const THUMB = { maxHeight: 180, maxWidth: 200 } as const;
+
+/**
+ * One image attachment. Its own component because the bytes are fetched through
+ * the authenticated client (see {@link useAttachmentObjectUrl}) and a hook can't
+ * be called from inside a `.map()`.
+ */
+function ImageAttachment({
+  a,
+  onView,
+}: {
+  a: SupportAttachmentDto;
+  onView: (a: SupportAttachmentDto, src: string) => void;
+}) {
+  const { src, failed } = useAttachmentObjectUrl(a.url);
+
+  if (failed) {
+    return (
+      <Group gap={6} c="dimmed">
+        <ImageOff size={14} />
+        <Text size="xs">Couldn't load {a.name}</Text>
+      </Group>
+    );
+  }
+
+  if (!src) {
+    return (
+      <Box
+        style={{
+          ...THUMB,
+          width: THUMB.maxWidth,
+          height: 120,
+          display: "grid",
+          placeItems: "center",
+          background: "var(--mantine-color-gray-1)",
+          borderRadius: 8,
+        }}
+      >
+        <Loader size="xs" color="edr-green" />
+      </Box>
+    );
+  }
+
+  return (
+    <Box
+      onClick={() => onView(a, src)}
+      style={{ cursor: "zoom-in", borderRadius: 8, overflow: "hidden" }}
+    >
+      <Image src={src} alt={a.name} radius="md" fit="cover" style={THUMB} />
+    </Box>
+  );
+}
+
+/**
+ * Attachments inside a message bubble: images as thumbnails, everything else as
+ * a labelled file row. Non-images are not fetched until opened — pulling every
+ * document in a thread just to draw a filename would be wasteful.
+ */
+export function MessageAttachments({
+  attachments,
+  mine,
+  onView,
+  onOpenFile,
+}: {
+  attachments: SupportAttachmentDto[];
+  mine: boolean;
+  onView: (a: SupportAttachmentDto, src: string) => void;
+  onOpenFile: (a: SupportAttachmentDto) => void;
+}) {
+  if (attachments.length === 0) return null;
+
+  return (
+    <Stack gap={6} mt={6}>
+      {attachments.map((a) =>
+        isSupportAttachmentImage(a.mimeType) ? (
+          <ImageAttachment key={a.id} a={a} onView={onView} />
+        ) : (
+          <Paper
+            key={a.id}
+            onClick={() => onOpenFile(a)}
+            px="sm"
+            py={6}
+            radius="md"
+            style={{
+              cursor: "pointer",
+              background: mine ? "rgba(255,255,255,0.16)" : "white",
+              border: mine ? "none" : "1px solid var(--mantine-color-gray-3)",
+            }}
+          >
+            <Group gap={8} wrap="nowrap">
+              <FileText size={16} style={{ flexShrink: 0 }} />
+              <Box style={{ minWidth: 0 }}>
+                <Text size="xs" fw={600} truncate>
+                  {a.name}
+                </Text>
+                <Text size="10px" opacity={0.75}>
+                  {formatBytes(a.size)}
+                </Text>
+              </Box>
+            </Group>
+          </Paper>
+        ),
+      )}
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/features/support/SupportPanel.tsx b/apps/edr-freight-web/portal/src/features/support/SupportPanel.tsx
index 77150866e..08afc19b8 100644
--- a/apps/edr-freight-web/portal/src/features/support/SupportPanel.tsx
+++ b/apps/edr-freight-web/portal/src/features/support/SupportPanel.tsx
@@ -1,4 +1,10 @@
-import { SupportAuthorRole, type SupportMessageDto } from "@edr/types";
+import {
+  SUPPORT_ATTACHMENT_ACCEPT,
+  SupportAuthorRole,
+  type SupportAttachmentDto,
+  type SupportMessageDto,
+} from "@edr/types";
+import { useFileViewer } from "@edr/ui-common";
 import {
   ActionIcon,
   Avatar,
@@ -12,9 +18,14 @@ import {
   Textarea,
   ThemeIcon,
 } from "@mantine/core";
-import { Headset, Send, X } from "lucide-react";
-import { useEffect, useRef, useState } from "react";
+import { Headset, Paperclip, Send, X } from "lucide-react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import toast from "react-hot-toast";
 
+import { AttachmentDraftBar } from "./AttachmentDraftBar";
+import { MessageAttachments } from "./MessageAttachments";
+import { useAttachmentDraft } from "./useAttachmentDraft";
+import { useLazyAttachmentObjectUrl } from "./useAttachmentObjectUrl";
 import {
   useConversation,
   useMarkConversationRead,
@@ -22,6 +33,9 @@ import {
   useSendMessage,
 } from "./useSupport";
 
+/** Distance from an edge (px) that counts as "at" it. */
+const SCROLL_EDGE_SLOP = 120;
+
 function formatTime(iso?: string | null): string {
   if (!iso) return "";
   const d = new Date(iso);
@@ -43,32 +57,136 @@ export interface SupportPanelProps {
  */
 export function SupportPanel({ onClose }: SupportPanelProps) {
   const { data: conversation } = useConversation();
-  const { data: messages, isLoading } = useMessages();
+  const {
+    messages,
+    pageCount,
+    isLoading,
+    hasNextPage,
+    isFetchingNextPage,
+    fetchNextPage,
+  } = useMessages();
   const send = useSendMessage();
   const markRead = useMarkConversationRead();
   const [draft, setDraft] = useState("");
+  const [dragging, setDragging] = useState(false);
   const viewport = useRef<HTMLDivElement>(null);
+  const fileInput = useRef<HTMLInputElement>(null);
+  const { view, viewer } = useFileViewer();
+  const attach = useAttachmentDraft((reason) => toast.error(reason));
+
+  /**
+   * Scroll height captured just before an older page was requested, tagged with
+   * the page count at that moment.
+   *
+   * The page count is what makes this safe. Keyed on presence alone, a message
+   * arriving over the socket while history was still in flight would consume the
+   * snapshot on a one-bubble append, and the real 30-message prepend would then
+   * land with nothing to correct against — throwing the reader exactly as far as
+   * this exists to prevent. Comparing counts means only an actual new page can
+   * claim it.
+   */
+  const pendingRestore = useRef<{ height: number; atPageCount: number } | null>(
+    null,
+  );
+  /** Whether the customer is parked at the bottom and wants to follow new messages. */
+  const stick = useRef(true);
+  /** Which thread the refs above describe; a switch resets them. */
+  const anchoredThread = useRef(conversation?.id);
 
   // Mark read on open + whenever new messages arrive. No-op before the thread
   // exists, so opening the panel never creates one.
   useEffect(() => {
     if (conversation) markRead.mutate();
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [conversation?.id, messages?.length]);
+  }, [conversation?.id, messages.length]);
 
-  // Auto-scroll to newest.
-  useEffect(() => {
-    viewport.current?.scrollTo({ top: viewport.current.scrollHeight });
-  }, [messages?.length]);
+  /**
+   * Keep the viewport sensible as the list changes underneath it.
+   *
+   * Two different things change `messages`, and they want opposite behaviour:
+   * a new message at the bottom should follow (if the customer is already
+   * there), while an older page prepended at the top must NOT move the content
+   * they're reading. Layout effect, not effect — this has to run before paint or
+   * the prepend visibly jumps.
+   */
+  useLayoutEffect(() => {
+    const el = viewport.current;
+    if (!el) return;
+
+    // A different thread underneath us (the first send creates one): start a
+    // fresh read at the bottom and drop the previous thread's anchoring state.
+    if (anchoredThread.current !== conversation?.id) {
+      anchoredThread.current = conversation?.id;
+      pendingRestore.current = null;
+      stick.current = true;
+      el.scrollTo({ top: el.scrollHeight });
+      return;
+    }
+
+    const restore = pendingRestore.current;
+    if (restore && pageCount > restore.atPageCount) {
+      // An older page went in above: push the scroll down by exactly the height
+      // that was added, so the same message stays under the cursor.
+      el.scrollTop += el.scrollHeight - restore.height;
+      pendingRestore.current = null;
+      return;
+    }
+    if (stick.current) el.scrollTo({ top: el.scrollHeight });
+  }, [messages, pageCount, conversation?.id]);
+
+  const onScroll = ({ y }: { y: number }) => {
+    const el = viewport.current;
+    if (!el) return;
+    stick.current = el.scrollHeight - y - el.clientHeight < SCROLL_EDGE_SLOP;
+    if (y < SCROLL_EDGE_SLOP && hasNextPage && !isFetchingNextPage) {
+      // A failed fetch leaves this set, which is harmless: the list didn't
+      // change, so the height is still accurate for the retry, and the count
+      // tag stops it being mistaken for a landed page in the meantime.
+      pendingRestore.current = {
+        height: el.scrollHeight,
+        atPageCount: pageCount,
+      };
+      fetchNextPage();
+    }
+  };
 
   const submit = async () => {
     const body = draft.trim();
-    if (!body) return;
+    if (!body && attach.attachments.length === 0) return;
+    const files = attach.files;
+    // Clear optimistically so the composer feels instant; on failure the text is
+    // restored below rather than silently lost.
     setDraft("");
-    await send.mutateAsync(body);
+    attach.clear();
+    stick.current = true;
+    try {
+      await send.mutateAsync({ body: body || undefined, attachments: files });
+    } catch (error) {
+      setDraft(body);
+      toast.error(
+        error instanceof Error ? error.message : "Couldn't send that message.",
+      );
+    }
   };
 
-  const isEmpty = !isLoading && (messages ?? []).length === 0;
+  const loadAttachment = useLazyAttachmentObjectUrl();
+
+  // Images already hold their bytes as an object URL from rendering the
+  // thumbnail, so reuse it rather than fetching the same file twice.
+  const openAttachment = (a: SupportAttachmentDto, src: string) =>
+    view({ name: a.name, url: src, mimeType: a.mimeType });
+
+  // Documents aren't fetched until opened.
+  const openFile = async (a: SupportAttachmentDto) => {
+    try {
+      const src = await loadAttachment(a.url);
+      view({ name: a.name, url: src, mimeType: a.mimeType });
+    } catch {
+      toast.error(`Couldn't open ${a.name}.`);
+    }
+  };
+
+  const isEmpty = !isLoading && messages.length === 0;
 
   return (
     <Paper
@@ -113,7 +231,12 @@ export function SupportPanel({ onClose }: SupportPanelProps) {
         </ActionIcon>
       </Group>
 
-      <ScrollArea style={{ flex: 1 }} viewportRef={viewport} type="hover">
+      <ScrollArea
+        style={{ flex: 1 }}
+        viewportRef={viewport}
+        type="hover"
+        onScrollPositionChange={onScroll}
+      >
         {isLoading ? (
           <Group justify="center" p="xl">
             <Loader size="sm" color="edr-green" />
@@ -129,24 +252,91 @@ export function SupportPanel({ onClose }: SupportPanelProps) {
           </Stack>
         ) : (
           <Stack gap="sm" p="md">
-            {(messages ?? []).map((m) => (
-              <MessageBubble key={m.id} m={m} />
+            {isFetchingNextPage && (
+              <Group justify="center" py="xs">
+                <Loader size="xs" color="edr-green" />
+              </Group>
+            )}
+            {!hasNextPage && (
+              <Text size="10px" c="dimmed" ta="center">
+                Start of conversation
+              </Text>
+            )}
+            {messages.map((m) => (
+              <MessageBubble
+                key={m.id}
+                m={m}
+                onView={openAttachment}
+                onOpenFile={openFile}
+              />
             ))}
           </Stack>
         )}
       </ScrollArea>
 
-      <Box p="sm" style={{ borderTop: "1px solid var(--mantine-color-gray-2)" }}>
+      <Box
+        p="sm"
+        style={{
+          borderTop: "1px solid var(--mantine-color-gray-2)",
+          background: dragging ? "var(--mantine-color-edr-green-0)" : undefined,
+          outline: dragging
+            ? "2px dashed var(--mantine-color-edr-green-6)"
+            : undefined,
+          outlineOffset: -4,
+        }}
+        onDragOver={(e) => {
+          e.preventDefault();
+          setDragging(true);
+        }}
+        onDragLeave={() => setDragging(false)}
+        onDrop={(e) => {
+          e.preventDefault();
+          setDragging(false);
+          attach.add(Array.from(e.dataTransfer.files));
+        }}
+      >
+        <AttachmentDraftBar
+          attachments={attach.attachments}
+          onRemove={attach.remove}
+        />
         <Group gap="xs" align="flex-end" wrap="nowrap">
+          <input
+            ref={fileInput}
+            type="file"
+            multiple
+            accept={SUPPORT_ATTACHMENT_ACCEPT}
+            hidden
+            onChange={(e) => {
+              attach.add(Array.from(e.currentTarget.files ?? []));
+              // Reset so picking the same file twice in a row still fires change.
+              e.currentTarget.value = "";
+            }}
+          />
+          <ActionIcon
+            size={38}
+            radius="md"
+            variant="subtle"
+            color="gray"
+            aria-label="Attach files"
+            onClick={() => fileInput.current?.click()}
+          >
+            <Paperclip size={18} />
+          </ActionIcon>
           <Textarea
             value={draft}
             onChange={(e) => setDraft(e.currentTarget.value)}
-            placeholder="Type a message…"
+            placeholder="Type a message, or paste an image…"
             autosize
             minRows={1}
             maxRows={4}
             radius="md"
             style={{ flex: 1 }}
+            // Screenshots land on the clipboard as files. Take them and suppress
+            // the default, which would otherwise also paste the image's name (or
+            // nothing) as text.
+            onPaste={(e) => {
+              if (attach.addFromPaste(e.clipboardData)) e.preventDefault();
+            }}
             onKeyDown={(e) => {
               if (e.key === "Enter" && !e.shiftKey) {
                 e.preventDefault();
@@ -160,18 +350,27 @@ export function SupportPanel({ onClose }: SupportPanelProps) {
             color="edr-green"
             variant="filled"
             loading={send.isPending}
-            disabled={!draft.trim()}
+            disabled={!draft.trim() && attach.attachments.length === 0}
             onClick={submit}
           >
             <Send size={18} />
           </ActionIcon>
         </Group>
       </Box>
+      {viewer}
     </Paper>
   );
 }
 
-function MessageBubble({ m }: { m: SupportMessageDto }) {
+function MessageBubble({
+  m,
+  onView,
+  onOpenFile,
+}: {
+  m: SupportMessageDto;
+  onView: (a: SupportAttachmentDto, src: string) => void;
+  onOpenFile: (a: SupportAttachmentDto) => void;
+}) {
   const mine = m.authorRole === SupportAuthorRole.CUSTOMER;
   return (
     <Group
@@ -204,9 +403,20 @@ function MessageBubble({ m }: { m: SupportMessageDto }) {
             borderBottomLeftRadius: mine ? undefined : 4,
           }}
         >
-          <Text size="sm" style={{ whiteSpace: "pre-wrap", wordBreak: "break-word" }}>
-            {m.body}
-          </Text>
+          {m.body && (
+            <Text
+              size="sm"
+              style={{ whiteSpace: "pre-wrap", wordBreak: "break-word" }}
+            >
+              {m.body}
+            </Text>
+          )}
+          <MessageAttachments
+            attachments={m.attachments}
+            mine={mine}
+            onView={onView}
+            onOpenFile={onOpenFile}
+          />
         </Paper>
         <Text size="10px" c="dimmed" mt={2} ta={mine ? "right" : "left"}>
           {formatTime(m.createdAt)}
diff --git a/apps/edr-freight-web/portal/src/features/support/SupportWidget.tsx b/apps/edr-freight-web/portal/src/features/support/SupportWidget.tsx
index e525c2496..3c06f2366 100644
--- a/apps/edr-freight-web/portal/src/features/support/SupportWidget.tsx
+++ b/apps/edr-freight-web/portal/src/features/support/SupportWidget.tsx
@@ -1,4 +1,4 @@
-import { SupportAuthorRole } from "@edr/types";
+import { SupportAuthorRole, type SupportMessageDto } from "@edr/types";
 import { Affix, Indicator, Transition } from "@mantine/core";
 import { Headset } from "lucide-react";
 import { useState } from "react";
@@ -10,6 +10,17 @@ import { SupportPanel } from "./SupportPanel";
 import { useSupportUnreadCount } from "./useSupport";
 import { useSupportSocket } from "./useSupportSocket";
 
+/**
+ * Toast blurb for an inbound reply. A message may carry files and no text at
+ * all, which would otherwise toast a bare "Support replied:".
+ */
+function previewOf(message: SupportMessageDto): string {
+  const body = message.body.trim();
+  if (body) return body.length > 60 ? `${body.slice(0, 60)}…` : body;
+  const count = message.attachments.length;
+  return count === 1 ? "sent a file" : `sent ${count} files`;
+}
+
 /**
  * Floating customer-support launcher, mounted in the authenticated app shell.
  * Shows an unread badge and opens the chat panel; live pushes keep the badge
@@ -23,12 +34,7 @@ export function SupportWidget() {
   useSupportSocket(isAuthenticated, (event) => {
     // Only the customer-visible side matters here; agent replies arrive as AGENT.
     if (!open && event.message.authorRole === SupportAuthorRole.AGENT) {
-      toast(
-        `Support replied: ${event.message.body.slice(0, 60)}${
-          event.message.body.length > 60 ? "…" : ""
-        }`,
-        { icon: "💬" },
-      );
+      toast(`Support replied: ${previewOf(event.message)}`, { icon: "💬" });
     }
   });
 
diff --git a/apps/edr-freight-web/portal/src/features/support/supportApi.ts b/apps/edr-freight-web/portal/src/features/support/supportApi.ts
index f04c73545..2d1a7aa6f 100644
--- a/apps/edr-freight-web/portal/src/features/support/supportApi.ts
+++ b/apps/edr-freight-web/portal/src/features/support/supportApi.ts
@@ -1,11 +1,38 @@
 import type {
   SendSupportMessageResult,
   SupportConversationDto,
-  SupportMessageDto,
+  SupportMessageListResult,
 } from "@edr/types";
 
 import { client } from "@/utils/api";
 
+export interface ListMessagesParams {
+  /** Opaque cursor from the previous page's `nextCursor`. */
+  before?: string;
+  limit?: number;
+}
+
+/** What the composer hands over: text, files, or both (never neither). */
+export interface SendMessageInput {
+  body?: string;
+  attachments?: File[];
+}
+
+/**
+ * A message with files goes as multipart so the server can persist them against
+ * the message it creates in the same request; text-only stays JSON. Letting
+ * axios set the multipart boundary itself is deliberate — setting
+ * `Content-Type` by hand omits the boundary and the request fails to parse.
+ */
+function toRequestBody(input: SendMessageInput): FormData | { body?: string } {
+  if (!input.attachments?.length) return { body: input.body };
+
+  const form = new FormData();
+  if (input.body) form.append("body", input.body);
+  for (const file of input.attachments) form.append("attachments", file);
+  return form;
+}
+
 /**
  * Portal support-chat REST calls. My company has exactly one thread, so nothing
  * here takes a conversation id — the server derives it from the caller.
@@ -20,14 +47,37 @@ export const supportApi = {
     const { data } = await client.get("/api/support/conversation");
     return data.data;
   },
-  listMessages: async (): Promise<SupportMessageDto[]> => {
-    const { data } = await client.get("/api/support/conversation/messages");
+  listMessages: async (
+    params: ListMessagesParams = {},
+  ): Promise<SupportMessageListResult> => {
+    const { data } = await client.get("/api/support/conversation/messages", {
+      params,
+    });
     return data.data;
   },
-  sendMessage: async (body: string): Promise<SendSupportMessageResult> => {
-    const { data } = await client.post("/api/support/conversation/messages", {
-      body,
-    });
+  /**
+   * Attachment bytes, fetched through the authenticated client.
+   *
+   * Deliberately not a direct `<img src={url}>`: the API guard reads the bearer
+   * token from the Authorization header only — there is no cookie fallback — and
+   * an `<img>` request cannot carry one, so a direct src is an unavoidable 401.
+   * The same reason `filesService.download` exists for booking documents. The
+   * caller wraps this blob in an object URL.
+   *
+   * `relativeUrl` is the DTO's `url` (`/api/support/attachments/:id`), so the
+   * route stays owned by the server.
+   */
+  fetchAttachment: async (relativeUrl: string): Promise<Blob> => {
+    const { data } = await client.get(relativeUrl, { responseType: "blob" });
+    return data as Blob;
+  },
+  sendMessage: async (
+    input: SendMessageInput,
+  ): Promise<SendSupportMessageResult> => {
+    const { data } = await client.post(
+      "/api/support/conversation/messages",
+      toRequestBody(input),
+    );
     return data.data;
   },
   markRead: async (): Promise<{ unreadCount: number }> => {
diff --git a/apps/edr-freight-web/portal/src/features/support/useAttachmentDraft.ts b/apps/edr-freight-web/portal/src/features/support/useAttachmentDraft.ts
new file mode 100644
index 000000000..bd30e970a
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/features/support/useAttachmentDraft.ts
@@ -0,0 +1,130 @@
+import {
+  isSupportAttachmentAllowed,
+  isSupportAttachmentImage,
+  SUPPORT_ATTACHMENT_MAX_BYTES,
+  SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+} from "@edr/types";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** A file staged in the composer, not yet sent. */
+export interface PendingAttachment {
+  /** Local-only id; the server id doesn't exist until the message is sent. */
+  id: string;
+  file: File;
+  /** Object URL, images only. Revoked when the entry goes away. */
+  previewUrl?: string;
+}
+
+let nextId = 0;
+
+/**
+ * Staging area for files being attached to a message.
+ *
+ * Files are held client-side until send, then posted alongside the text in one
+ * multipart request — there's no upload-then-reference step, so nothing to
+ * garbage-collect if the customer changes their mind.
+ *
+ * Object URLs for image previews are revoked on removal and unmount; without
+ * that, the widget — which lives for the whole session in the app shell — would
+ * hold the full bytes of every image ever staged for the life of the tab.
+ */
+export function useAttachmentDraft(onReject?: (reason: string) => void) {
+  const [attachments, setAttachments] = useState<PendingAttachment[]>([]);
+  const rejectRef = useRef(onReject);
+  rejectRef.current = onReject;
+
+  // Read from a ref in the unmount cleanup so it doesn't re-run (and revoke
+  // still-live URLs) on every change to the list.
+  const attachmentsRef = useRef(attachments);
+  attachmentsRef.current = attachments;
+  useEffect(
+    () => () => {
+      for (const a of attachmentsRef.current) {
+        if (a.previewUrl) URL.revokeObjectURL(a.previewUrl);
+      }
+    },
+    [],
+  );
+
+  const add = useCallback((files: File[]) => {
+    if (files.length === 0) return;
+    setAttachments((current) => {
+      const accepted: PendingAttachment[] = [];
+      for (const file of files) {
+        if (
+          current.length + accepted.length >=
+          SUPPORT_ATTACHMENT_MAX_PER_MESSAGE
+        ) {
+          rejectRef.current?.(
+            `Up to ${SUPPORT_ATTACHMENT_MAX_PER_MESSAGE} files per message.`,
+          );
+          break;
+        }
+        if (!isSupportAttachmentAllowed(file.type)) {
+          rejectRef.current?.(`${file.name}: that file type isn't supported.`);
+          continue;
+        }
+        if (file.size > SUPPORT_ATTACHMENT_MAX_BYTES) {
+          rejectRef.current?.(
+            `${file.name} is over the ${
+              SUPPORT_ATTACHMENT_MAX_BYTES / (1024 * 1024)
+            }MB limit.`,
+          );
+          continue;
+        }
+        accepted.push({
+          id: `pending-${nextId++}`,
+          file,
+          previewUrl: isSupportAttachmentImage(file.type)
+            ? URL.createObjectURL(file)
+            : undefined,
+        });
+      }
+      return accepted.length ? [...current, ...accepted] : current;
+    });
+  }, []);
+
+  const remove = useCallback((id: string) => {
+    setAttachments((current) => {
+      const target = current.find((a) => a.id === id);
+      if (target?.previewUrl) URL.revokeObjectURL(target.previewUrl);
+      return current.filter((a) => a.id !== id);
+    });
+  }, []);
+
+  const clear = useCallback(() => {
+    setAttachments((current) => {
+      for (const a of current) {
+        if (a.previewUrl) URL.revokeObjectURL(a.previewUrl);
+      }
+      return [];
+    });
+  }, []);
+
+  /**
+   * Pull files off a paste. Returns true if anything was taken, so the caller
+   * can suppress the default paste — otherwise pasting a screenshot also drops
+   * its filename (or nothing) into the textarea.
+   *
+   * Copying an image in most apps puts BOTH the bitmap and some text/html on the
+   * clipboard, so check for files first and only then let the text through.
+   */
+  const addFromPaste = useCallback(
+    (clipboard: DataTransfer | null): boolean => {
+      const files = Array.from(clipboard?.files ?? []);
+      if (files.length === 0) return false;
+      add(files);
+      return true;
+    },
+    [add],
+  );
+
+  return {
+    attachments,
+    files: attachments.map((a) => a.file),
+    add,
+    addFromPaste,
+    remove,
+    clear,
+  };
+}
diff --git a/apps/edr-freight-web/portal/src/features/support/useAttachmentObjectUrl.ts b/apps/edr-freight-web/portal/src/features/support/useAttachmentObjectUrl.ts
new file mode 100644
index 000000000..9253b7690
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/features/support/useAttachmentObjectUrl.ts
@@ -0,0 +1,80 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { supportApi } from "./supportApi";
+
+/**
+ * Blob object URL for an attachment, or `undefined` while it loads / on failure.
+ *
+ * Chat attachments cannot be rendered with a direct `<img src={a.url}>`. The API
+ * guard takes the bearer token from the `Authorization` header and has no cookie
+ * fallback, and an `<img>` request cannot carry that header — a direct src is an
+ * unavoidable 401. So the bytes are fetched through the authenticated client and
+ * handed to the browser as an object URL, the same way booking documents are
+ * downloaded.
+ *
+ * The URL is revoked on unmount and whenever the attachment changes, so a thread
+ * scrolled through hundreds of images doesn't pin all of them in memory.
+ */
+export function useAttachmentObjectUrl(relativeUrl: string): {
+  src?: string;
+  failed: boolean;
+} {
+  const [src, setSrc] = useState<string>();
+  const [failed, setFailed] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    let created: string | undefined;
+
+    setSrc(undefined);
+    setFailed(false);
+
+    supportApi
+      .fetchAttachment(relativeUrl)
+      .then((blob) => {
+        // The component may have unmounted mid-flight; creating a URL then would
+        // leak it, since the cleanup below has already run.
+        if (cancelled) return;
+        created = URL.createObjectURL(blob);
+        setSrc(created);
+      })
+      .catch(() => {
+        if (!cancelled) setFailed(true);
+      });
+
+    return () => {
+      cancelled = true;
+      if (created) URL.revokeObjectURL(created);
+    };
+  }, [relativeUrl]);
+
+  return { src, failed };
+}
+
+/**
+ * On-demand variant for files that aren't previewed inline (documents): fetch
+ * only when the user actually opens one, rather than pulling every attachment in
+ * the thread down just to render a filename row.
+ *
+ * Holds a single slot — opening another file revokes the previous URL, as does
+ * unmounting.
+ */
+export function useLazyAttachmentObjectUrl(): (
+  relativeUrl: string,
+) => Promise<string> {
+  const current = useRef<string>();
+
+  useEffect(
+    () => () => {
+      if (current.current) URL.revokeObjectURL(current.current);
+    },
+    [],
+  );
+
+  return useCallback(async (relativeUrl: string) => {
+    const blob = await supportApi.fetchAttachment(relativeUrl);
+    if (current.current) URL.revokeObjectURL(current.current);
+    current.current = URL.createObjectURL(blob);
+    return current.current;
+  }, []);
+}
diff --git a/apps/edr-freight-web/portal/src/features/support/useSupport.ts b/apps/edr-freight-web/portal/src/features/support/useSupport.ts
index d89a8f701..0fa2c3f69 100644
--- a/apps/edr-freight-web/portal/src/features/support/useSupport.ts
+++ b/apps/edr-freight-web/portal/src/features/support/useSupport.ts
@@ -1,13 +1,28 @@
-import type { SupportConversationDto } from "@edr/types";
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type {
+  SupportConversationDto,
+  SupportMessageDto,
+  SupportMessageListResult,
+} from "@edr/types";
+import {
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type InfiniteData,
+  type QueryClient,
+} from "@tanstack/react-query";
+import { useMemo } from "react";
 
-import { supportApi } from "./supportApi";
+import { supportApi, type SendMessageInput } from "./supportApi";
 
 export const SUPPORT_KEY = ["support"] as const;
 export const SUPPORT_CONVERSATION_KEY = ["support", "conversation"] as const;
 export const SUPPORT_MESSAGES_KEY = ["support", "messages"] as const;
 export const SUPPORT_UNREAD_KEY = ["support", "unread"] as const;
 
+/** Messages per page in the thread. */
+const MESSAGES_PAGE_SIZE = 30;
+
 /** My company's support thread — null until the first message is sent. */
 export function useConversation(enabled = true) {
   return useQuery({
@@ -17,13 +32,83 @@ export function useConversation(enabled = true) {
   });
 }
 
-/** The thread's messages, oldest first. Empty until the thread exists. */
+/**
+ * The thread's messages, paged backwards from newest.
+ *
+ * react-query's "next page" is *older* history here, so `pages` runs
+ * newest-block-first and has to be reversed to render top-to-bottom in time
+ * order. Cursor-based rather than offset so a message arriving mid-scroll
+ * doesn't shift the pages already loaded.
+ */
 export function useMessages(enabled = true) {
-  return useQuery({
+  const query = useInfiniteQuery({
     queryKey: SUPPORT_MESSAGES_KEY,
-    queryFn: () => supportApi.listMessages(),
+    queryFn: ({ pageParam }) =>
+      supportApi.listMessages({ before: pageParam, limit: MESSAGES_PAGE_SIZE }),
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
     enabled,
   });
+
+  const messages = useMemo(
+    () => [...(query.data?.pages ?? [])].reverse().flatMap((p) => p.items),
+    [query.data],
+  );
+
+  // Exposed so the view can tell a prepended history page from a message
+  // appended at the bottom — `messages` changing says nothing about which.
+  return { ...query, messages, pageCount: query.data?.pages.length ?? 0 };
+}
+
+/**
+ * Splice a newly-arrived message into the cached thread.
+ *
+ * Deliberately not `invalidateQueries`: the thread is paginated, so that would
+ * refetch *every* page the customer has scrolled back through — making the cost
+ * of each inbound message grow with how far they've read. Page 0 is the newest
+ * block and its items are oldest-first within the block, so the new message
+ * belongs on its end.
+ *
+ * The socket only ever pushes this company's own thread, so there's no id to
+ * match on. Nothing is written when nothing is cached — the panel isn't
+ * rendering it, and a seeded one-message page would carry no `nextCursor` and
+ * strand the history.
+ */
+/**
+ * Why this reports an outcome rather than a boolean: the two ways it can decline
+ * to append need opposite handling. A duplicate is the sender's own echo and must
+ * be ignored — refetching there would undo the whole point. "Uncached" means the
+ * thread's first page is still in flight and may have been read on the server
+ * *before* this message existed, so dropping it silently would lose it until
+ * something else happened to refetch; the caller refetches instead. That's cheap
+ * precisely because nothing is loaded yet.
+ */
+export type AppendOutcome = "appended" | "duplicate" | "uncached";
+
+export function appendMessageToCache(
+  qc: QueryClient,
+  message: SupportMessageDto,
+): AppendOutcome {
+  let outcome: AppendOutcome = "uncached";
+  qc.setQueryData<InfiniteData<SupportMessageListResult>>(
+    SUPPORT_MESSAGES_KEY,
+    (current) => {
+      if (!current?.pages.length) return current;
+      const [newest, ...rest] = current.pages;
+      // Our own message arrives twice — once as the POST response, once as the
+      // socket echo. Ignore the duplicate rather than render it twice.
+      if (newest.items.some((m) => m.id === message.id)) {
+        outcome = "duplicate";
+        return current;
+      }
+      outcome = "appended";
+      return {
+        ...current,
+        pages: [{ ...newest, items: [...newest.items, message] }, ...rest],
+      };
+    },
+  );
+  return outcome;
 }
 
 export function useSupportUnreadCount(enabled = true) {
@@ -40,9 +125,12 @@ export function useSupportUnreadCount(enabled = true) {
 export function useSendMessage() {
   const qc = useQueryClient();
   return useMutation({
-    mutationFn: (body: string) => supportApi.sendMessage(body),
+    mutationFn: (input: SendMessageInput) => supportApi.sendMessage(input),
+    // The gateway echoes our own message back over the socket, which appends it
+    // to the cache — so don't invalidate the thread here or every send would
+    // refetch every page the customer has scrolled through. The conversation
+    // itself still needs a refresh: the first send is what creates it.
     onSuccess: () => {
-      qc.invalidateQueries({ queryKey: SUPPORT_MESSAGES_KEY });
       qc.invalidateQueries({ queryKey: SUPPORT_CONVERSATION_KEY });
     },
   });
diff --git a/apps/edr-freight-web/portal/src/features/support/useSupportSocket.ts b/apps/edr-freight-web/portal/src/features/support/useSupportSocket.ts
index 0e5c578c8..2b931e246 100644
--- a/apps/edr-freight-web/portal/src/features/support/useSupportSocket.ts
+++ b/apps/edr-freight-web/portal/src/features/support/useSupportSocket.ts
@@ -11,6 +11,7 @@ import { io } from "socket.io-client";
 import { API_BASE_URL } from "@/constants/apiConfig";
 
 import {
+  appendMessageToCache,
   SUPPORT_CONVERSATION_KEY,
   SUPPORT_MESSAGES_KEY,
   SUPPORT_UNREAD_KEY,
@@ -29,9 +30,9 @@ const SOCKET_ORIGIN = String(API_BASE_URL ?? "").replace(/\/api\/?$/, "");
 
 /**
  * Subscribes to live support-chat pushes for the signed-in customer. The company
- * only has one thread, so any push refreshes it wholesale — messages, the
- * conversation itself, and the unread badge — and fires `onMessage` (the widget
- * shows a toast when the panel is closed).
+ * only has one thread, so every push belongs to it: the message goes straight
+ * into the thread cache, the conversation and unread badge are refreshed, and
+ * `onMessage` fires (the widget shows a toast when the panel is closed).
  */
 export function useSupportSocket(
   enabled: boolean,
@@ -52,12 +53,23 @@ export function useSupportSocket(
       withCredentials: true,
     });
 
-    socket.on(SUPPORT_CHAT_WS_EVENTS.MESSAGE_NEW, (event: SupportMessageEvent) => {
-      qc.invalidateQueries({ queryKey: SUPPORT_MESSAGES_KEY });
-      qc.invalidateQueries({ queryKey: SUPPORT_CONVERSATION_KEY });
-      qc.invalidateQueries({ queryKey: SUPPORT_UNREAD_KEY });
-      onMessageRef.current?.(event);
-    });
+    socket.on(
+      SUPPORT_CHAT_WS_EVENTS.MESSAGE_NEW,
+      (event: SupportMessageEvent) => {
+        // Append rather than invalidate: the thread is paginated, and invalidating
+        // it would refetch every page the customer has scrolled back through on
+        // every single inbound message.
+        if (appendMessageToCache(qc, event.message) === "uncached") {
+          // The thread's first page is still loading and may have been read before
+          // this message existed — without this it would go missing until some
+          // unrelated refetch. Cheap: there are no pages to re-fetch yet.
+          qc.invalidateQueries({ queryKey: SUPPORT_MESSAGES_KEY });
+        }
+        qc.invalidateQueries({ queryKey: SUPPORT_CONVERSATION_KEY });
+        qc.invalidateQueries({ queryKey: SUPPORT_UNREAD_KEY });
+        onMessageRef.current?.(event);
+      },
+    );
 
     socket.on(
       SUPPORT_CHAT_WS_EVENTS.CONVERSATION_UPDATED,

From 59cecd44e796c3113b55b1bcdf9e9e649ddf4f91 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 18 Jul 2026 09:36:35 +0000
Subject: [PATCH 05/15] chore: chat types update

---
 packages/types/src/common/index.ts            |  1 +
 .../types/src/common/support-attachments.ts   | 73 +++++++++++++++++++
 packages/types/src/freight/support-chat.ts    | 57 ++++++++++++++-
 packages/types/src/passenger/support-chat.ts  | 63 +++++++++++++++-
 4 files changed, 189 insertions(+), 5 deletions(-)
 create mode 100644 packages/types/src/common/support-attachments.ts

diff --git a/packages/types/src/common/index.ts b/packages/types/src/common/index.ts
index 317898d80..21158afe3 100644
--- a/packages/types/src/common/index.ts
+++ b/packages/types/src/common/index.ts
@@ -1,5 +1,6 @@
 export * from "./payments";
 export * from "./payment-messaging";
+export * from "./support-attachments";
 
 export interface BaseEntity {
   id: string;
diff --git a/packages/types/src/common/support-attachments.ts b/packages/types/src/common/support-attachments.ts
new file mode 100644
index 000000000..1f6a1b376
--- /dev/null
+++ b/packages/types/src/common/support-attachments.ts
@@ -0,0 +1,73 @@
+/**
+ * Rules shared by the freight and passenger support-chat attachment flows.
+ *
+ * The two chat backends are independent implementations (freight: TypeORM +
+ * polymorphic `FileRecord`; passenger: Prisma + `SupportAttachment`), but the
+ * *contract* a client codes against — what may be uploaded, how large, how the
+ * preview URL behaves — must not drift between them. Keep the limits here so
+ * both APIs validate identically and all four web apps can render one consistent
+ * "file too large / type not allowed" message.
+ */
+
+/** `FileRecord.resource` discriminator for freight chat attachments. */
+export const SUPPORT_ATTACHMENT_RESOURCE = "support_message";
+
+/** Per-file ceiling. Enforced server-side; the UI pre-checks to fail fast. */
+export const SUPPORT_ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+
+/** Max files on a single message. */
+export const SUPPORT_ATTACHMENT_MAX_PER_MESSAGE = 10;
+
+/**
+ * How long a minted preview URL stays valid. Long enough that an open thread
+ * doesn't rot mid-read, short enough that a leaked URL isn't a durable grant.
+ */
+export const SUPPORT_ATTACHMENT_URL_TTL_SECONDS = 60 * 60;
+
+/**
+ * Types accepted on a chat message.
+ *
+ * Deliberately NARROWER than `FilesService.ALLOWED_UPLOAD_MIME` (which also
+ * serves generated PDFs and scanned business documents at 25MB). Chat is
+ * user-to-user, so the blast radius of a bad file is another human clicking it.
+ *
+ * `image/svg+xml` is excluded on purpose and must stay excluded: an SVG is
+ * executable markup, and previewing one inline (`<img>` is safe, but an
+ * `<iframe>`/direct navigation is not) executes any script it carries under the
+ * serving origin. Nothing in chat needs vector uploads.
+ */
+export const SUPPORT_ATTACHMENT_ALLOWED_MIME: readonly string[] = [
+  // images (previewable inline)
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+  "image/gif",
+  // documents
+  "application/pdf",
+  "application/msword",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "application/vnd.ms-excel",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  "text/csv",
+  "text/plain",
+];
+
+/** Image subset — these are the ones worth rendering as a thumbnail. */
+export const SUPPORT_ATTACHMENT_IMAGE_MIME: readonly string[] = [
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+  "image/gif",
+];
+
+export function isSupportAttachmentImage(mimeType: string): boolean {
+  return SUPPORT_ATTACHMENT_IMAGE_MIME.includes(mimeType);
+}
+
+export function isSupportAttachmentAllowed(mimeType: string): boolean {
+  return SUPPORT_ATTACHMENT_ALLOWED_MIME.includes(mimeType);
+}
+
+/** `accept` attribute for a file input / paste target. */
+export const SUPPORT_ATTACHMENT_ACCEPT =
+  SUPPORT_ATTACHMENT_ALLOWED_MIME.join(",");
diff --git a/packages/types/src/freight/support-chat.ts b/packages/types/src/freight/support-chat.ts
index 84b9a7262..6d7e69973 100644
--- a/packages/types/src/freight/support-chat.ts
+++ b/packages/types/src/freight/support-chat.ts
@@ -16,12 +16,37 @@
  * constants shared by the gateway (emitter) and both web apps (subscribers).
  */
 
+import { SUPPORT_ATTACHMENT_RESOURCE } from "../common/support-attachments";
+
 /** Who authored a message — the customer side or a backoffice agent. */
 export enum SupportAuthorRole {
   CUSTOMER = "CUSTOMER",
   AGENT = "AGENT",
 }
 
+/** `FileRecord.resource` value chat attachments are stored under. */
+export { SUPPORT_ATTACHMENT_RESOURCE };
+
+/** A file attached to a support message. */
+export interface SupportAttachmentDto {
+  /**
+   * FileRecord id. For an authenticated download use
+   * `GET /support/attachments/:id?download=1` — the generic `GET /files/:id`
+   * route deliberately refuses chat attachments (it has no ownership check).
+   */
+  id: string;
+  name: string;
+  mimeType: string;
+  /** Bytes. */
+  size: number;
+  /**
+   * Short-lived signed URL for inline preview (`<img src>`), minted per response.
+   * Expires — see SUPPORT_ATTACHMENT_URL_TTL_SECONDS. Clients must not persist it;
+   * refetch the thread to renew.
+   */
+  url: string;
+}
+
 /** A single chat message on the wire. */
 export interface SupportMessageDto {
   id: string;
@@ -30,7 +55,9 @@ export interface SupportMessageDto {
   authorRole: SupportAuthorRole;
   /** Display name of the author, resolved at send time (best-effort). */
   authorName?: string | null;
+  /** Empty string for attachment-only messages. */
   body: string;
+  attachments: SupportAttachmentDto[];
   createdAt: string;
 }
 
@@ -54,9 +81,17 @@ export interface SupportConversationDto {
   updatedAt: string;
 }
 
-/** Post a message. The portal omits the id; the thread is implied by the company. */
+/**
+ * Post a message. The portal omits the id; the thread is implied by the company.
+ *
+ * Attachments do not travel in this shape — a message carrying files is sent as
+ * `multipart/form-data` with a `body` field plus one or more `attachments` file
+ * parts, so the files are written with `resourceId = message.id` in the same
+ * request. There is no staging area and therefore no orphan-file GC to run.
+ */
 export interface SendSupportMessageDto {
-  body: string;
+  /** Optional only when the request carries at least one attachment. */
+  body?: string;
 }
 
 /** Agent opens a thread with a company that has none yet. */
@@ -81,6 +116,24 @@ export interface SupportConversationListResult {
   unreadCount: number;
 }
 
+/**
+ * A page of messages, walking **backwards** from newest.
+ *
+ * Chat pages by keyset, not by offset: an inbound message while an agent is
+ * scrolled back would shift every offset by one and duplicate/skip rows across
+ * pages. The cursor pins a fixed point in (createdAt, id), so concurrent inserts
+ * at the head can't disturb pages already read.
+ */
+export interface SupportMessageListResult {
+  /** Oldest-first *within the page*, so a page appends/prepends as a block. */
+  items: SupportMessageDto[];
+  /**
+   * Opaque cursor for the next (older) page; null when the thread's start has
+   * been reached. Pass back as `before`.
+   */
+  nextCursor: string | null;
+}
+
 /** Socket.io event names pushed server → client on the `support-chat` namespace. */
 export const SUPPORT_CHAT_WS_EVENTS = {
   /** A new message was added to a conversation the socket can see. */
diff --git a/packages/types/src/passenger/support-chat.ts b/packages/types/src/passenger/support-chat.ts
index 254b64e55..e6b7d1219 100644
--- a/packages/types/src/passenger/support-chat.ts
+++ b/packages/types/src/passenger/support-chat.ts
@@ -23,6 +23,33 @@ export enum PassengerSupportSender {
   AGENT = "AGENT",
 }
 
+/**
+ * A file attached to a passenger support message.
+ *
+ * Structurally identical to the freight `SupportAttachmentDto` — kept as its own
+ * declaration because the two namespaces are independently versioned and the
+ * backing stores differ (Prisma `SupportAttachment` here, polymorphic
+ * `FileRecord` in freight). The upload rules themselves are shared: see
+ * `SUPPORT_ATTACHMENT_*` in `common/support-attachments`.
+ */
+export interface PassengerSupportAttachmentDto {
+  id: string;
+  name: string;
+  mimeType: string;
+  /** Bytes. */
+  size: number;
+  /**
+   * Short-lived signed URL — serves both inline preview and download. Expires
+   * (see SUPPORT_ATTACHMENT_URL_TTL_SECONDS); clients must not persist it,
+   * refetch the thread to renew.
+   *
+   * There is no API-streamed alternative here, unlike freight: this app has no
+   * general file endpoint, so the signed URL is the only handle. It is minted
+   * only into responses the caller was already authorized to receive.
+   */
+  url: string;
+}
+
 /** A single chat message on the wire. */
 export interface PassengerSupportMessageDto {
   id: string;
@@ -30,7 +57,9 @@ export interface PassengerSupportMessageDto {
   sender: PassengerSupportSender;
   /** Display name of the author, best-effort. */
   authorName?: string | null;
+  /** Empty string for attachment-only messages. */
   text: string;
+  attachments: PassengerSupportAttachmentDto[];
   createdAt: string;
 }
 
@@ -74,15 +103,43 @@ export interface CreateGuestSupportConversationDto {
   initialMessage: string;
 }
 
-/** Post a message into an existing conversation. */
+/**
+ * Post a message into an existing conversation.
+ *
+ * As in freight, attachments travel as `multipart/form-data` (a `text` field
+ * plus `attachments` file parts) rather than as ids in this body, so files are
+ * persisted against the message that owns them in one request.
+ */
 export interface SendPassengerSupportMessageDto {
-  text: string;
+  /** Optional only when the request carries at least one attachment. */
+  text?: string;
 }
 
-/** The single device-scoped thread for the portal: conversation + its messages. */
+/**
+ * The single device-scoped thread for the portal: conversation + its newest page
+ * of messages.
+ *
+ * `messages` is the *first page only* (newest N, oldest-first within the page) —
+ * it is not the whole thread. Page backwards with `nextCursor` via the messages
+ * endpoint, exactly as the backoffice does.
+ */
 export interface PassengerSupportThreadDto {
   conversation: PassengerSupportConversationDto | null;
   messages: PassengerSupportMessageDto[];
+  /** Cursor for the next (older) page; null when the thread's start is loaded. */
+  nextCursor: string | null;
+}
+
+/**
+ * A page of messages, walking backwards from newest. Keyset — not offset — so a
+ * message arriving while the reader is scrolled back cannot shift or duplicate
+ * pages already fetched. See the freight twin for the full rationale.
+ */
+export interface PassengerSupportMessageListResult {
+  /** Oldest-first within the page. */
+  items: PassengerSupportMessageDto[];
+  /** Pass back as `before`; null at the start of the thread. */
+  nextCursor: string | null;
 }
 
 /** Paginated list envelope for the conversations list endpoints. */

From 779af4c3484cc36a8502dab0b44d7e95042447cb Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 18 Jul 2026 09:44:14 +0000
Subject: [PATCH 06/15] feat: setup the attachment to the passenger api

---
 apps/edr-passenger-api/package.json           |   2 +
 .../migration.sql                             |  39 ++
 apps/edr-passenger-api/prisma/schema.prisma   |  31 +-
 .../src/modules/storage/minio.config.ts       |  20 +
 .../src/modules/storage/minio.service.ts      |  90 +++++
 .../src/modules/storage/storage.module.ts     |  12 +
 .../support/attachment-upload.options.ts      |  20 +
 .../src/modules/support/message-cursor.ts     |  52 +++
 .../src/modules/support/support.controller.ts | 195 ++++++++--
 .../src/modules/support/support.dto.ts        |  64 ++-
 .../src/modules/support/support.module.ts     |   4 +-
 .../src/modules/support/support.service.ts    | 368 ++++++++++++++----
 12 files changed, 781 insertions(+), 116 deletions(-)
 create mode 100644 apps/edr-passenger-api/prisma/migrations/20260717090000_support_chat_attachments/migration.sql
 create mode 100644 apps/edr-passenger-api/src/modules/storage/minio.config.ts
 create mode 100644 apps/edr-passenger-api/src/modules/storage/minio.service.ts
 create mode 100644 apps/edr-passenger-api/src/modules/storage/storage.module.ts
 create mode 100644 apps/edr-passenger-api/src/modules/support/attachment-upload.options.ts
 create mode 100644 apps/edr-passenger-api/src/modules/support/message-cursor.ts

diff --git a/apps/edr-passenger-api/package.json b/apps/edr-passenger-api/package.json
index cdfe68787..a9ee85156 100644
--- a/apps/edr-passenger-api/package.json
+++ b/apps/edr-passenger-api/package.json
@@ -52,6 +52,7 @@
     "express": "^4.18.2",
     "helmet": "^8.0.0",
     "jose": "^5.10.0",
+    "minio": "7.1.3",
     "pg": "^8.21.0",
     "qrcode": "^1.5.3",
     "reflect-metadata": "^0.2.2",
@@ -71,6 +72,7 @@
     "@types/express": "^4.17.21",
     "@types/jest": "^29.5.11",
     "@types/luxon": "^3.7.1",
+    "@types/multer": "^2.1.0",
     "@types/node": "^20.10.6",
     "@types/qrcode": "^1.5.5",
     "@types/supertest": "^6.0.2",
diff --git a/apps/edr-passenger-api/prisma/migrations/20260717090000_support_chat_attachments/migration.sql b/apps/edr-passenger-api/prisma/migrations/20260717090000_support_chat_attachments/migration.sql
new file mode 100644
index 000000000..ca2605812
--- /dev/null
+++ b/apps/edr-passenger-api/prisma/migrations/20260717090000_support_chat_attachments/migration.sql
@@ -0,0 +1,39 @@
+-- Support chat attachments.
+--
+-- `SupportMessage.text` becomes nullable so an attachment-only message can say
+-- "there is no text" instead of smuggling that through an empty string. This is
+-- a catalog-only change in Postgres — no table rewrite, no long lock.
+ALTER TABLE "SupportMessage" ALTER COLUMN "text" DROP NOT NULL;
+
+-- The `attachments` JSONB column has been dead since the init migration: never
+-- written, never read, absent from every DTO. It is dropped rather than reused —
+-- an untyped blob gives no file identity, no size accounting, and nothing to
+-- cascade on delete. Real rows replace it below. (The name is also needed for
+-- the new relation.)
+ALTER TABLE "SupportMessage" DROP COLUMN "attachments";
+
+-- Backs keyset pagination of a thread (newest-first over (createdAt, id)).
+-- Without it, paging a long thread degrades to a scan per page.
+-- CreateIndex
+CREATE INDEX "SupportMessage_conversationId_createdAt_idx" ON "SupportMessage"("conversationId", "createdAt");
+
+-- CreateTable
+CREATE TABLE "SupportAttachment" (
+    "id" TEXT NOT NULL,
+    "messageId" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "mimeType" TEXT NOT NULL,
+    "size" INTEGER NOT NULL,
+    "url" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "SupportAttachment_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "SupportAttachment_messageId_idx" ON "SupportAttachment"("messageId");
+
+-- AddForeignKey
+-- CASCADE: an attachment has no meaning without its message. (Object bytes in
+-- MinIO are not reaped by this — deleting messages is not a flow that exists.)
+ALTER TABLE "SupportAttachment" ADD CONSTRAINT "SupportAttachment_messageId_fkey" FOREIGN KEY ("messageId") REFERENCES "SupportMessage"("id") ON DELETE CASCADE ON UPDATE CASCADE;
diff --git a/apps/edr-passenger-api/prisma/schema.prisma b/apps/edr-passenger-api/prisma/schema.prisma
index 62f658967..09a1ffa8c 100644
--- a/apps/edr-passenger-api/prisma/schema.prisma
+++ b/apps/edr-passenger-api/prisma/schema.prisma
@@ -917,10 +917,37 @@ model SupportMessage {
   id             String              @id @default(uuid())
   conversationId String
   sender         SupportSender
-  text           String
-  attachments    Json?
+  /// NULL for an attachment-only message — absence of text is representable
+  /// rather than smuggled through "". The DTO maps NULL -> "".
+  text           String?
   createdAt      DateTime            @default(now())
   conversation   SupportConversation @relation(fields: [conversationId], references: [id])
+  attachments    SupportAttachment[]
+  /// Backs keyset pagination of a thread (newest-first over (createdAt, id)).
+  /// Without it, paging a long thread degrades to a scan per page.
+  @@index([conversationId, createdAt])
+  @@schema("passenger")
+}
+
+/// A file posted on a support message.
+///
+/// The freight side stores the equivalent in its polymorphic `freight.files`
+/// table; this app has no such table (and no TypeORM), so chat attachments get a
+/// purpose-built model rather than a shared one. Bytes live in MinIO — `url` is
+/// the unsigned object path, signed on read for preview.
+model SupportAttachment {
+  id        String         @id @default(uuid())
+  messageId String
+  name      String
+  mimeType  String
+  /// Bytes.
+  size      Int
+  /// Unsigned MinIO object URL. Not directly fetchable by a browser — the API
+  /// mints a short-lived signed URL per response.
+  url       String
+  createdAt DateTime       @default(now())
+  message   SupportMessage @relation(fields: [messageId], references: [id], onDelete: Cascade)
+  @@index([messageId])
   @@schema("passenger")
 }
 
diff --git a/apps/edr-passenger-api/src/modules/storage/minio.config.ts b/apps/edr-passenger-api/src/modules/storage/minio.config.ts
new file mode 100644
index 000000000..67df0f0ef
--- /dev/null
+++ b/apps/edr-passenger-api/src/modules/storage/minio.config.ts
@@ -0,0 +1,20 @@
+import { registerAs } from '@nestjs/config';
+
+/**
+ * Mirrors the freight API's MinIO config so both apps read the same env vars and
+ * behave the same against the same object store. Kept as a copy rather than a
+ * shared package because the two APIs share no runtime code today, and a config
+ * package for six fields would be more coupling than it saves.
+ */
+export const minioConfig = registerAs('minio', () => ({
+  endPoint: process.env.MINIO_ENDPOINT || 'minio-dev.smart.aaca.gov.et',
+  port: parseInt(process.env.MINIO_PORT || '443', 10),
+  useSSL: process.env.MINIO_USE_SSL !== 'false',
+  accessKey: process.env.MINIO_ACCESS_KEY || '',
+  secretKey: process.env.MINIO_SECRET_KEY || '',
+  bucket: process.env.MINIO_BUCKET || 'edr-dev',
+  // Preset the region so presignedGetObject signs URLs locally. Without it the
+  // minio client fires a live GetBucketLocation request on every sign, which
+  // blocks (no timeout) when MinIO is slow and would hang every thread load.
+  region: process.env.MINIO_REGION || 'us-east-1',
+}));
diff --git a/apps/edr-passenger-api/src/modules/storage/minio.service.ts b/apps/edr-passenger-api/src/modules/storage/minio.service.ts
new file mode 100644
index 000000000..f10e0babf
--- /dev/null
+++ b/apps/edr-passenger-api/src/modules/storage/minio.service.ts
@@ -0,0 +1,90 @@
+import { Inject, Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { ConfigType } from '@nestjs/config';
+import { Client } from 'minio';
+import { Readable } from 'stream';
+
+import { minioConfig } from './minio.config';
+
+/**
+ * Minimal object-storage client for the passenger API.
+ *
+ * A deliberate subset of the freight MinioService — only what chat attachments
+ * need (put, sign, stream, key-from-url). Freight's extra surface (delete,
+ * public URLs for unauthenticated links) is omitted rather than copied
+ * speculatively.
+ */
+@Injectable()
+export class MinioService {
+  private readonly client: Client;
+  private readonly logger = new Logger(MinioService.name);
+  private readonly bucket: string;
+
+  constructor(
+    @Inject(minioConfig.KEY)
+    private readonly config: ConfigType<typeof minioConfig>,
+  ) {
+    this.bucket = config.bucket;
+    this.client = new Client({
+      endPoint: config.endPoint,
+      port: config.port,
+      useSSL: config.useSSL,
+      accessKey: config.accessKey,
+      secretKey: config.secretKey,
+      region: config.region,
+    });
+  }
+
+  async uploadFile(objectName: string, buffer: Buffer, contentType: string): Promise<string> {
+    await this.client.putObject(this.bucket, objectName, buffer, buffer.length, {
+      'Content-Type': contentType,
+    });
+    return this.getObjectUrl(objectName);
+  }
+
+  /** Unsigned object URL — what gets persisted. Not browser-fetchable. */
+  getObjectUrl(objectName: string): string {
+    const protocol = this.config.useSSL ? 'https' : 'http';
+    return `${protocol}://${this.config.endPoint}:${this.config.port}/${this.bucket}/${objectName}`;
+  }
+
+  getObjectNameFromUrl(value: string): string {
+    const trimmed = value.trim();
+    if (!trimmed) throw new NotFoundException('File object path is empty');
+    if (!/^https?:\/\//i.test(trimmed)) return trimmed.replace(/^\/+/, '');
+
+    const url = new URL(trimmed);
+    // pathname percent-encodes the key (a space becomes "%20") but MinIO stores
+    // the literal characters, so decode each segment or a file whose name had
+    // spaces 404s with "specified key does not exist".
+    const parts = url.pathname
+      .split('/')
+      .filter(Boolean)
+      .map((segment) => decodeURIComponent(segment));
+    if (parts[0] === this.bucket) parts.shift();
+
+    const objectName = parts.join('/');
+    if (!objectName) throw new NotFoundException('File object path is empty');
+    return objectName;
+  }
+
+  async getFileStream(objectName: string): Promise<Readable> {
+    return this.client.getObject(this.bucket, objectName);
+  }
+
+  /**
+   * Short-lived signed URL for inline preview.
+   *
+   * Unlike the freight twin this does NOT degrade to an unsigned public URL when
+   * signing fails: a chat attachment is another passenger's file, and quietly
+   * handing back a URL that only works if the bucket is world-readable trades a
+   * visible error for a silent access-control surprise. Fail loudly instead.
+   */
+  async getSignedUrl(objectName: string, expirySeconds: number): Promise<string> {
+    try {
+      return await this.client.presignedGetObject(this.bucket, objectName, expirySeconds);
+    } catch (error) {
+      this.logger.error(`Failed to sign URL for ${objectName}: ${(error as Error).message}`);
+      throw error;
+    }
+  }
+}
diff --git a/apps/edr-passenger-api/src/modules/storage/storage.module.ts b/apps/edr-passenger-api/src/modules/storage/storage.module.ts
new file mode 100644
index 000000000..14ae3de45
--- /dev/null
+++ b/apps/edr-passenger-api/src/modules/storage/storage.module.ts
@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+
+import { minioConfig } from './minio.config';
+import { MinioService } from './minio.service';
+
+@Module({
+  imports: [ConfigModule.forFeature(minioConfig)],
+  providers: [MinioService],
+  exports: [MinioService],
+})
+export class StorageModule {}
diff --git a/apps/edr-passenger-api/src/modules/support/attachment-upload.options.ts b/apps/edr-passenger-api/src/modules/support/attachment-upload.options.ts
new file mode 100644
index 000000000..9a182436c
--- /dev/null
+++ b/apps/edr-passenger-api/src/modules/support/attachment-upload.options.ts
@@ -0,0 +1,20 @@
+import { SUPPORT_ATTACHMENT_MAX_BYTES, SUPPORT_ATTACHMENT_MAX_PER_MESSAGE } from '@edr/types';
+import { MulterOptions } from '@nestjs/platform-express/multer/interfaces/multer-options.interface';
+
+/** Multipart field name carrying chat files. */
+export const SUPPORT_ATTACHMENT_FIELD = 'attachments';
+
+/**
+ * Multer-level caps for the chat send routes.
+ *
+ * These duplicate `SupportService.assertSendable` on purpose and don't replace
+ * it: Multer stops reading the socket once a part exceeds `fileSize`, so an
+ * oversized upload is cut off mid-stream rather than buffered into memory and
+ * rejected afterwards. The service check produces the readable error.
+ */
+export const supportAttachmentMulterOptions: MulterOptions = {
+  limits: {
+    fileSize: SUPPORT_ATTACHMENT_MAX_BYTES,
+    files: SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+  },
+};
diff --git a/apps/edr-passenger-api/src/modules/support/message-cursor.ts b/apps/edr-passenger-api/src/modules/support/message-cursor.ts
new file mode 100644
index 000000000..5194ad808
--- /dev/null
+++ b/apps/edr-passenger-api/src/modules/support/message-cursor.ts
@@ -0,0 +1,52 @@
+import { BadRequestException } from '@nestjs/common';
+
+/**
+ * Keyset cursor for paging a thread backwards from newest.
+ *
+ * The sort key is the pair `(createdAt, id)`, not `createdAt` alone: two
+ * messages can share a millisecond, and a cursor on a non-unique key either
+ * re-serves or skips the tied rows depending which side of the boundary they
+ * land on. The id breaks ties with a stable total order.
+ *
+ * Deliberately a twin of the freight API's `message-cursor.ts`, not a shared
+ * import: the two APIs share no runtime package, and @edr/types is Nest-free by
+ * design (this throws Nest exceptions). The wire format matches so a client can
+ * treat both chats identically — keep them in step if either changes.
+ */
+export interface MessageCursor {
+  createdAt: Date;
+  id: string;
+}
+
+export function encodeMessageCursor(cursor: MessageCursor): string {
+  return Buffer.from(`${cursor.createdAt.toISOString()}|${cursor.id}`, 'utf8').toString(
+    'base64url',
+  );
+}
+
+/**
+ * Parse a client-supplied cursor. Rejects anything malformed rather than
+ * silently falling back to "first page" — a corrupted cursor that degrades to
+ * page 1 makes an infinite scroll loop forever over the same rows.
+ */
+export function decodeMessageCursor(raw: string): MessageCursor {
+  let decoded: string;
+  try {
+    decoded = Buffer.from(raw, 'base64url').toString('utf8');
+  } catch {
+    throw new BadRequestException('Malformed pagination cursor.');
+  }
+
+  const separator = decoded.lastIndexOf('|');
+  if (separator === -1) {
+    throw new BadRequestException('Malformed pagination cursor.');
+  }
+
+  const createdAt = new Date(decoded.slice(0, separator));
+  const id = decoded.slice(separator + 1);
+  if (Number.isNaN(createdAt.getTime()) || !id) {
+    throw new BadRequestException('Malformed pagination cursor.');
+  }
+
+  return { createdAt, id };
+}
diff --git a/apps/edr-passenger-api/src/modules/support/support.controller.ts b/apps/edr-passenger-api/src/modules/support/support.controller.ts
index 4404c3ea8..563e71104 100644
--- a/apps/edr-passenger-api/src/modules/support/support.controller.ts
+++ b/apps/edr-passenger-api/src/modules/support/support.controller.ts
@@ -7,21 +7,33 @@ import {
   Post,
   Query,
   Req,
+  Res,
   UnauthorizedException,
+  UploadedFiles,
   UseGuards,
+  UseInterceptors,
 } from '@nestjs/common';
-import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
+import { FilesInterceptor } from '@nestjs/platform-express';
+import { Response } from 'express';
+import { ApiTags, ApiOperation, ApiBearerAuth, ApiBody, ApiConsumes } from '@nestjs/swagger';
+import { SUPPORT_ATTACHMENT_MAX_PER_MESSAGE } from '@edr/types';
 import { IsPublic } from '@tria-plc/api-common/modules/auth/decorators/public.decorator';
 import { SupportService } from './support.service';
 import { JwtGuard } from '../../common/jwt.guard';
+import {
+  SUPPORT_ATTACHMENT_FIELD,
+  supportAttachmentMulterOptions,
+} from './attachment-upload.options';
 import {
   CreateConversationDto,
   CreateGuestConversationDto,
   DeviceIdBodyDto,
   DeviceSendMessageDto,
+  DeviceThreadQueryDto,
   GuestIdBodyDto,
   GuestSendMessageDto,
   ListConversationsQueryDto,
+  ListMessagesQueryDto,
   SendMessageDto,
   UpdateStatusDto,
 } from './support.dto';
@@ -32,6 +44,35 @@ function userId(req: any): string {
   return id;
 }
 
+/**
+ * Multipart send routes accept `text` + `attachments` file parts; a plain-JSON
+ * body still works (Multer passes non-multipart requests through untouched), so
+ * text-only clients are unaffected.
+ */
+const attachmentsInterceptor = () =>
+  UseInterceptors(
+    FilesInterceptor(
+      SUPPORT_ATTACHMENT_FIELD,
+      SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+      supportAttachmentMulterOptions,
+    ),
+  );
+
+/** Swagger body schema for a send route: optional text + optional files. */
+const sendBodySchema = (extra: Record<string, unknown> = {}) => ({
+  schema: {
+    type: 'object',
+    properties: {
+      ...extra,
+      text: { type: 'string' },
+      attachments: {
+        type: 'array',
+        items: { type: 'string', format: 'binary' },
+      },
+    },
+  },
+});
+
 @ApiTags('Support')
 @Controller('support')
 export class SupportController {
@@ -74,19 +115,37 @@ export class SupportController {
   @Get('conversations/:id/messages')
   @UseGuards(JwtGuard)
   @ApiBearerAuth('JWT-auth')
-  @ApiOperation({ summary: 'List messages in one of my conversations' })
-  messages(@Req() req: any, @Param('id') id: string) {
-    return this.service.getMessages(id, { iamUserId: userId(req) });
+  @ApiOperation({
+    summary: 'List messages in one of my conversations (newest page first)',
+    description:
+      'Keyset-paginated backwards from newest. Omit `before` for the newest ' +
+      'page, then pass the previous `nextCursor`. Null means start of thread.',
+  })
+  messages(@Req() req: any, @Param('id') id: string, @Query() query: ListMessagesQueryDto) {
+    return this.service.getMessages(id, query, { iamUserId: userId(req) });
   }
 
   @Post('conversations/:id/messages')
   @UseGuards(JwtGuard)
   @ApiBearerAuth('JWT-auth')
+  @attachmentsInterceptor()
+  @ApiConsumes('multipart/form-data', 'application/json')
+  @ApiBody(sendBodySchema())
+  @ApiBearerAuth('JWT-auth')
   @ApiOperation({ summary: 'Send a message as the customer' })
-  send(@Req() req: any, @Param('id') id: string, @Body() body: SendMessageDto) {
-    return this.service.sendMessage(id, 'USER', body.text, {
-      iamUserId: userId(req),
-    });
+  send(
+    @Req() req: any,
+    @Param('id') id: string,
+    @Body() body: SendMessageDto,
+    @UploadedFiles() attachments?: Express.Multer.File[],
+  ) {
+    return this.service.sendMessage(
+      id,
+      'USER',
+      body.text,
+      { iamUserId: userId(req) },
+      attachments ?? [],
+    );
   }
 
   @Post('conversations/:id/read')
@@ -111,16 +170,29 @@ export class SupportController {
 
   @Get('device/thread')
   @IsPublic()
-  @ApiOperation({ summary: "Get the device's support thread + messages" })
-  deviceThread(@Query('deviceId') deviceId: string) {
-    return this.service.getDeviceThread(deviceId);
+  @ApiOperation({
+    summary: "Get the device's support thread + its newest page of messages",
+    description:
+      '`messages` is the newest page only, not the whole thread — page back ' +
+      'with `nextCursor` via this same route.',
+  })
+  deviceThread(@Query() query: DeviceThreadQueryDto) {
+    return this.service.getDeviceThread(query.deviceId, query);
   }
 
   @Post('device/messages')
   @IsPublic()
-  @ApiOperation({ summary: 'Send a message (creates the thread on first send)' })
-  deviceSend(@Body() body: DeviceSendMessageDto) {
-    return this.service.sendDeviceMessage(body.deviceId, body.text);
+  @attachmentsInterceptor()
+  @ApiConsumes('multipart/form-data', 'application/json')
+  @ApiBody(sendBodySchema({ deviceId: { type: 'string' } }))
+  @ApiOperation({
+    summary: 'Send a message (creates the thread on first send)',
+  })
+  deviceSend(
+    @Body() body: DeviceSendMessageDto,
+    @UploadedFiles() attachments?: Express.Multer.File[],
+  ) {
+    return this.service.sendDeviceMessage(body.deviceId, body.text, attachments ?? []);
   }
 
   @Post('device/read')
@@ -137,6 +209,37 @@ export class SupportController {
     return this.service.unreadCount('USER', { guestId: deviceId });
   }
 
+  // ---- chat attachments --------------------------------------------------
+
+  /**
+   * Serves both audiences (portal device threads and the backoffice inbox) from
+   * one path, because a new message is pushed to both over the socket in a
+   * single payload — an identity-bearing URL would be wrong for one of them.
+   *
+   * Public for the same reason the device thread is: access to a passenger
+   * support thread is already whoever-holds-the-id. See `streamAttachment` for
+   * the full trade-off and the TODO to tighten it with the agent-route gating.
+   */
+  @Get('attachments/:fileId')
+  @IsPublic()
+  @ApiOperation({ summary: 'Stream a support chat attachment' })
+  async attachment(
+    @Param('fileId') fileId: string,
+    @Query('download') download: string | undefined,
+    @Res() res: Response,
+  ) {
+    const { stream, mimeType, name } = await this.service.streamAttachment(fileId);
+    const forceDownload = download === '1' || download === 'true';
+
+    res.setHeader('Content-Type', mimeType);
+    res.setHeader(
+      'Content-Disposition',
+      `${forceDownload ? 'attachment' : 'inline'}; filename="${name}"`,
+    );
+    res.setHeader('Cache-Control', 'private, max-age=300');
+    stream.pipe(res);
+  }
+
   // ---- customer: guest (unauthenticated, multi-ticket) ------------------
   // No JwtGuard. Access is scoped by a client-generated `guestId` (the bearer
   // of access — anyone with it sees that thread; accepted MVP trade-off).
@@ -150,28 +253,42 @@ export class SupportController {
 
   @Get('guest/conversations')
   @IsPublic()
-  @ApiOperation({ summary: 'List a guest\'s conversations' })
-  guestList(
-    @Query('guestId') guestId: string,
-    @Query() query: ListConversationsQueryDto,
-  ) {
+  @ApiOperation({ summary: "List a guest's conversations" })
+  guestList(@Query('guestId') guestId: string, @Query() query: ListConversationsQueryDto) {
     return this.service.listForCustomer({ guestId }, query);
   }
 
   @Get('guest/conversations/:id/messages')
   @IsPublic()
-  @ApiOperation({ summary: 'List messages in a guest conversation' })
-  guestMessages(@Param('id') id: string, @Query('guestId') guestId: string) {
-    return this.service.getMessages(id, { guestId });
+  @ApiOperation({
+    summary: 'List messages in a guest conversation (newest page first)',
+  })
+  guestMessages(
+    @Param('id') id: string,
+    @Query('guestId') guestId: string,
+    @Query() query: ListMessagesQueryDto,
+  ) {
+    return this.service.getMessages(id, query, { guestId });
   }
 
   @Post('guest/conversations/:id/messages')
   @IsPublic()
+  @attachmentsInterceptor()
+  @ApiConsumes('multipart/form-data', 'application/json')
+  @ApiBody(sendBodySchema({ guestId: { type: 'string' } }))
   @ApiOperation({ summary: 'Send a message as a guest' })
-  guestSend(@Param('id') id: string, @Body() body: GuestSendMessageDto) {
-    return this.service.sendMessage(id, 'USER', body.text, {
-      guestId: body.guestId,
-    });
+  guestSend(
+    @Param('id') id: string,
+    @Body() body: GuestSendMessageDto,
+    @UploadedFiles() attachments?: Express.Multer.File[],
+  ) {
+    return this.service.sendMessage(
+      id,
+      'USER',
+      body.text,
+      { guestId: body.guestId },
+      attachments ?? [],
+    );
   }
 
   @Post('guest/conversations/:id/read')
@@ -183,7 +300,7 @@ export class SupportController {
 
   @Get('guest/unread-count')
   @IsPublic()
-  @ApiOperation({ summary: 'Count a guest\'s unread conversations' })
+  @ApiOperation({ summary: "Count a guest's unread conversations" })
   guestUnread(@Query('guestId') guestId: string) {
     return this.service.unreadCount('USER', { guestId });
   }
@@ -202,17 +319,29 @@ export class SupportController {
   @Get('agent/conversations/:id/messages')
   @UseGuards(JwtGuard)
   @ApiBearerAuth('JWT-auth')
-  @ApiOperation({ summary: 'List messages in a conversation' })
-  agentMessages(@Param('id') id: string) {
-    return this.service.getMessages(id);
+  @ApiOperation({
+    summary: 'List messages in a conversation (newest page first)',
+    description:
+      'Keyset-paginated backwards from newest. Omit `before` for the newest ' +
+      'page, then pass the previous `nextCursor`. Null means start of thread.',
+  })
+  agentMessages(@Param('id') id: string, @Query() query: ListMessagesQueryDto) {
+    return this.service.getMessages(id, query);
   }
 
   @Post('agent/conversations/:id/messages')
   @UseGuards(JwtGuard)
   @ApiBearerAuth('JWT-auth')
-  @ApiOperation({ summary: 'Reply as an agent' })
-  agentSend(@Param('id') id: string, @Body() body: SendMessageDto) {
-    return this.service.sendMessage(id, 'AGENT', body.text);
+  @attachmentsInterceptor()
+  @ApiConsumes('multipart/form-data', 'application/json')
+  @ApiBody(sendBodySchema())
+  @ApiOperation({ summary: 'Reply as an agent, optionally with attachments' })
+  agentSend(
+    @Param('id') id: string,
+    @Body() body: SendMessageDto,
+    @UploadedFiles() attachments?: Express.Multer.File[],
+  ) {
+    return this.service.sendMessage(id, 'AGENT', body.text, undefined, attachments ?? []);
   }
 
   @Patch('agent/conversations/:id/status')
diff --git a/apps/edr-passenger-api/src/modules/support/support.dto.ts b/apps/edr-passenger-api/src/modules/support/support.dto.ts
index a60ac607e..4936cb2e3 100644
--- a/apps/edr-passenger-api/src/modules/support/support.dto.ts
+++ b/apps/edr-passenger-api/src/modules/support/support.dto.ts
@@ -32,12 +32,19 @@ export class CreateConversationDto {
   initialMessage!: string;
 }
 
+/**
+ * Text is optional across the send DTOs because a message may be nothing but
+ * attachments. "Neither text nor files" is rejected in the service rather than
+ * here — the validator can't see the multipart file parts.
+ */
 export class SendMessageDto {
-  @ApiProperty({ description: 'Message text.' })
+  @ApiPropertyOptional({
+    description: 'Message text. Optional only when attachments are present.',
+  })
+  @IsOptional()
   @IsString()
-  @MinLength(1)
   @MaxLength(4000)
-  text!: string;
+  text?: string;
 }
 
 export class CreateGuestConversationDto {
@@ -79,11 +86,13 @@ export class GuestSendMessageDto {
   @Length(8, 120)
   guestId!: string;
 
-  @ApiProperty({ description: 'Message text.' })
+  @ApiPropertyOptional({
+    description: 'Message text. Optional only when attachments are present.',
+  })
+  @IsOptional()
   @IsString()
-  @MinLength(1)
   @MaxLength(4000)
-  text!: string;
+  text?: string;
 }
 
 export class GuestIdBodyDto {
@@ -99,11 +108,13 @@ export class DeviceSendMessageDto {
   @Length(8, 120)
   deviceId!: string;
 
-  @ApiProperty({ description: 'Message text.' })
+  @ApiPropertyOptional({
+    description: 'Message text. Optional only when attachments are present.',
+  })
+  @IsOptional()
   @IsString()
-  @MinLength(1)
   @MaxLength(4000)
-  text!: string;
+  text?: string;
 }
 
 export class DeviceIdBodyDto {
@@ -145,3 +156,38 @@ export class ListConversationsQueryDto {
   @Max(100)
   limit?: number;
 }
+
+/** Default page size for a thread — roughly two screens of bubbles. */
+export const SUPPORT_MESSAGES_DEFAULT_LIMIT = 30;
+export const SUPPORT_MESSAGES_MAX_LIMIT = 100;
+
+export class ListMessagesQueryDto {
+  @ApiPropertyOptional({
+    description:
+      "Opaque cursor from a previous response's `nextCursor`. Returns the page " +
+      'of messages immediately OLDER than the cursor. Omit for the newest page.',
+  })
+  @IsOptional()
+  @IsString()
+  before?: string;
+
+  @ApiPropertyOptional({
+    minimum: 1,
+    maximum: SUPPORT_MESSAGES_MAX_LIMIT,
+    default: SUPPORT_MESSAGES_DEFAULT_LIMIT,
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(SUPPORT_MESSAGES_MAX_LIMIT)
+  limit?: number;
+}
+
+/** Query form of {@link ListMessagesQueryDto} for the device-scoped thread. */
+export class DeviceThreadQueryDto extends ListMessagesQueryDto {
+  @ApiProperty({ description: 'Client device id (localStorage).' })
+  @IsString()
+  @Length(8, 120)
+  deviceId!: string;
+}
diff --git a/apps/edr-passenger-api/src/modules/support/support.module.ts b/apps/edr-passenger-api/src/modules/support/support.module.ts
index 136fcf196..e4dd50b25 100644
--- a/apps/edr-passenger-api/src/modules/support/support.module.ts
+++ b/apps/edr-passenger-api/src/modules/support/support.module.ts
@@ -2,6 +2,7 @@ import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { Session } from '@tria-plc/iamapi-common/entities/iam/user/session.entity';
 
+import { StorageModule } from '../storage/storage.module';
 import { SupportController } from './support.controller';
 import { SupportService } from './support.service';
 import { SupportGateway } from './support.gateway';
@@ -10,7 +11,8 @@ import { WsAuthService } from './ws-auth.service';
 @Module({
   // Session is served by the app's default TypeORM DataSource (IAM schema) —
   // used by WsAuthService to authenticate WebSocket handshakes.
-  imports: [TypeOrmModule.forFeature([Session])],
+  // StorageModule — MinioService for chat attachment bytes.
+  imports: [TypeOrmModule.forFeature([Session]), StorageModule],
   controllers: [SupportController],
   providers: [SupportService, SupportGateway, WsAuthService],
 })
diff --git a/apps/edr-passenger-api/src/modules/support/support.service.ts b/apps/edr-passenger-api/src/modules/support/support.service.ts
index 77f701bf2..89929626d 100644
--- a/apps/edr-passenger-api/src/modules/support/support.service.ts
+++ b/apps/edr-passenger-api/src/modules/support/support.service.ts
@@ -1,16 +1,52 @@
 import {
+  BadRequestException,
   ForbiddenException,
   Injectable,
   NotFoundException,
 } from '@nestjs/common';
-import { Passenger as T } from '@edr/types';
+import {
+  isSupportAttachmentAllowed,
+  Passenger as T,
+  SUPPORT_ATTACHMENT_MAX_BYTES,
+  SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+} from '@edr/types';
+import { randomUUID } from 'crypto';
+import { Readable } from 'stream';
 import { PrismaService } from '../../common/prisma.service';
+import { MinioService } from '../storage/minio.service';
+import { decodeMessageCursor, encodeMessageCursor } from './message-cursor';
+import { SUPPORT_MESSAGES_DEFAULT_LIMIT } from './support.dto';
 import { SupportGateway } from './support.gateway';
 
 type Side = 'USER' | 'AGENT';
 type PrismaSender = 'USER' | 'BOT' | 'AGENT';
 type PrismaStatus = 'OPEN' | 'RESOLVED' | 'CLOSED';
 
+/** Stand-in preview for a message that is nothing but files. */
+const ATTACHMENT_ONLY_PREVIEW = '📎';
+
+interface MessagesQuery {
+  before?: string;
+  limit?: number;
+}
+
+type AttachmentRow = {
+  id: string;
+  name: string;
+  mimeType: string;
+  size: number;
+  url: string;
+};
+
+type MessageRow = {
+  id: string;
+  conversationId: string;
+  sender: PrismaSender;
+  text: string | null;
+  createdAt: Date;
+  attachments?: AttachmentRow[];
+};
+
 /** Who the caller is on the customer side: an authed passenger or a guest. */
 export interface CustomerOwner {
   iamUserId?: string | null;
@@ -50,6 +86,7 @@ export class SupportService {
   constructor(
     private prisma: PrismaService,
     private gateway: SupportGateway,
+    private minio: MinioService,
   ) {}
 
   // ---- FAQ (unchanged) ---------------------------------------------------
@@ -115,29 +152,37 @@ export class SupportService {
 
   // ---- customer: device-scoped single thread (portal) -------------------
 
-  /** The device's single conversation + its messages ({conversation:null} if none). */
-  async getDeviceThread(deviceId: string): Promise<T.PassengerSupportThreadDto> {
-    if (!deviceId) return { conversation: null, messages: [] };
+  /**
+   * The device's single conversation + its NEWEST page of messages
+   * ({conversation:null} if none). Not the whole thread — the client pages back
+   * with `nextCursor` exactly as the backoffice does.
+   */
+  async getDeviceThread(
+    deviceId: string,
+    query: MessagesQuery = {},
+  ): Promise<T.PassengerSupportThreadDto> {
+    const empty = { conversation: null, messages: [], nextCursor: null };
+    if (!deviceId) return empty;
     const c = (await this.prisma.supportConversation.findFirst({
       where: { guestId: deviceId },
       orderBy: { createdAt: 'asc' },
     })) as ConversationRow | null;
-    if (!c) return { conversation: null, messages: [] };
-    const rows = await this.prisma.supportMessage.findMany({
-      where: { conversationId: c.id },
-      orderBy: { createdAt: 'asc' },
-    });
+    if (!c) return empty;
+
+    const page = await this.listMessages(c.id, query);
     const unread = await this.computeUnread([c], 'USER');
     return {
       conversation: this.toConversationDto(c, unread.get(c.id) ?? 0),
-      messages: rows.map((m) => this.toMessageDto(m)),
+      messages: page.items,
+      nextCursor: page.nextCursor,
     };
   }
 
   /** Append a message to the device's thread, creating it on first message. */
   async sendDeviceMessage(
     deviceId: string,
-    text: string,
+    text: string | undefined,
+    attachments: Express.Multer.File[] = [],
   ): Promise<T.PassengerSupportMessageDto> {
     let c = (await this.prisma.supportConversation.findFirst({
       where: { guestId: deviceId },
@@ -148,9 +193,7 @@ export class SupportService {
         data: { guestId: deviceId, subject: 'Support chat', status: 'OPEN' },
       })) as ConversationRow;
     }
-    const updated = await this.appendMessage(c, 'USER', text);
-    const last = updated.messages[updated.messages.length - 1];
-    return this.toMessageDto(last);
+    return this.appendMessage(c, 'USER', text, attachments);
   }
 
   /** Mark the device's thread read (customer side). */
@@ -186,9 +229,7 @@ export class SupportService {
 
   // ---- agent (backoffice) ------------------------------------------------
 
-  async listForAgents(
-    query: ListQuery,
-  ): Promise<T.PassengerSupportConversationListResult> {
+  async listForAgents(query: ListQuery): Promise<T.PassengerSupportConversationListResult> {
     const where = this.listWhere(query);
     const rows = (await this.prisma.supportConversation.findMany({
       where,
@@ -216,32 +257,29 @@ export class SupportService {
 
   // ---- shared ------------------------------------------------------------
 
+  /** One page of a thread, newest first. See {@link listMessages}. */
   async getMessages(
     conversationId: string,
+    query: MessagesQuery = {},
     asCustomer?: CustomerOwner,
-  ): Promise<T.PassengerSupportMessageDto[]> {
+  ): Promise<T.PassengerSupportMessageListResult> {
     const conversation = await this.requireConversation(conversationId);
     if (asCustomer) this.assertOwns(conversation, asCustomer);
-    const rows = await this.prisma.supportMessage.findMany({
-      where: { conversationId },
-      orderBy: { createdAt: 'asc' },
-    });
-    return rows.map((m) => this.toMessageDto(m));
+    return this.listMessages(conversationId, query);
   }
 
   async sendMessage(
     conversationId: string,
     sender: Side,
-    text: string,
+    text: string | undefined,
     asCustomer?: CustomerOwner,
+    attachments: Express.Multer.File[] = [],
   ): Promise<T.PassengerSupportMessageDto> {
     const conversation = await this.requireConversation(conversationId);
     if (sender === 'USER') {
       this.assertOwns(conversation, asCustomer ?? {});
     }
-    const updated = await this.appendMessage(conversation, sender, text);
-    const last = updated.messages[updated.messages.length - 1];
-    return this.toMessageDto(last);
+    return this.appendMessage(conversation, sender, text, attachments);
   }
 
   async markRead(
@@ -265,10 +303,7 @@ export class SupportService {
     return this.unreadCount('AGENT');
   }
 
-  async unreadCount(
-    side: Side,
-    owner?: CustomerOwner,
-  ): Promise<{ unreadCount: number }> {
+  async unreadCount(side: Side, owner?: CustomerOwner): Promise<{ unreadCount: number }> {
     const rows = (await this.prisma.supportConversation.findMany({
       where: side === 'USER' ? this.ownerScope(owner ?? {}) : {},
       select: { id: true, userLastReadAt: true, agentLastReadAt: true },
@@ -289,49 +324,197 @@ export class SupportService {
     conversation: ConversationRow,
     text: string,
   ): Promise<T.PassengerSupportConversationDto> {
-    const { conversation: updated } = await this.appendMessageRaw(
-      conversation,
-      'USER',
-      text,
-    );
+    const { conversation: updated } = await this.appendMessageRaw(conversation, 'USER', text);
     return this.toConversationDto(updated, 0);
   }
 
   private async appendMessage(
     conversation: ConversationRow,
     sender: PrismaSender,
-    text: string,
-  ) {
-    const { conversation: updated } = await this.appendMessageRaw(
-      conversation,
-      sender,
-      text,
-    );
-    return updated as ConversationRow & { messages: any[] };
+    text: string | undefined,
+    attachments: Express.Multer.File[] = [],
+  ): Promise<T.PassengerSupportMessageDto> {
+    const { message } = await this.appendMessageRaw(conversation, sender, text, attachments);
+    return message;
   }
 
-  /** Persist a message, bump the conversation's denormalized fields, emit live. */
+  /**
+   * One page of a thread, walking backwards from newest.
+   *
+   * Keyset, not offset: a message arriving while the reader is scrolled back
+   * would shift every offset by one and duplicate/skip rows across pages. Rides
+   * the (conversationId, createdAt) index; the id is a tiebreak for messages
+   * sharing a millisecond.
+   */
+  private async listMessages(
+    conversationId: string,
+    query: MessagesQuery,
+  ): Promise<T.PassengerSupportMessageListResult> {
+    const limit = query.limit ?? SUPPORT_MESSAGES_DEFAULT_LIMIT;
+    const before = query.before ? decodeMessageCursor(query.before) : undefined;
+
+    const rows = (await this.prisma.supportMessage.findMany({
+      where: {
+        conversationId,
+        ...(before
+          ? {
+              // Strictly older than the cursor in (createdAt, id) order.
+              OR: [
+                { createdAt: { lt: before.createdAt } },
+                {
+                  createdAt: before.createdAt,
+                  id: { lt: before.id },
+                },
+              ],
+            }
+          : {}),
+      },
+      orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
+      // One more than asked, to tell "there's another page" from "this page was
+      // simply full" without a second COUNT.
+      take: limit + 1,
+      include: { attachments: { orderBy: { createdAt: 'asc' } } },
+    })) as MessageRow[];
+
+    const hasMore = rows.length > limit;
+    const page = hasMore ? rows.slice(0, limit) : rows;
+    const oldest = page[page.length - 1];
+    const nextCursor =
+      hasMore && oldest
+        ? encodeMessageCursor({ createdAt: oldest.createdAt, id: oldest.id })
+        : null;
+
+    // Flip to oldest-first so a page prepends as one block.
+    const items = await Promise.all([...page].reverse().map((m) => this.toMessageDto(m)));
+    return { items, nextCursor };
+  }
+
+  /** Persist a message (+ attachments), bump denormalized fields, emit live. */
   private async appendMessageRaw(
     conversation: ConversationRow,
     sender: PrismaSender,
-    text: string,
-  ): Promise<{ conversation: ConversationRow & { messages: any[] }; message: any }> {
+    text: string | undefined,
+    attachments: Express.Multer.File[] = [],
+  ): Promise<{
+    conversation: ConversationRow;
+    message: T.PassengerSupportMessageDto;
+  }> {
+    const trimmed = (text ?? '').trim();
+    this.assertSendable(trimmed, attachments);
+
     const message = await this.prisma.supportMessage.create({
-      data: { conversationId: conversation.id, sender, text },
+      // NULL, not "", so "no text" is representable rather than inferred. The
+      // DTO flattens it back to "" for rendering.
+      data: { conversationId: conversation.id, sender, text: trimmed || null },
     });
+
+    // The row has to exist before the files, since each is stored against
+    // `messageId`. That leaves a window: if an upload fails here, the message is
+    // already committed. Undo it rather than leave the thread with a
+    // permanently blank bubble — there is no delete flow, so an orphan would be
+    // unremovable, and an attachment-only message that lost its files has no
+    // content at all.
+    let stored: AttachmentRow[];
+    try {
+      stored = await this.storeAttachments(message.id, attachments);
+    } catch (error) {
+      await this.prisma.supportMessage.delete({ where: { id: message.id } });
+      throw error;
+    }
+
     const updated = (await this.prisma.supportConversation.update({
       where: { id: conversation.id },
       data: {
         lastMessageAt: message.createdAt,
-        lastMessagePreview: text.slice(0, 280),
+        lastMessagePreview: this.buildPreview(trimmed, stored),
         lastMessageSender: sender,
       },
-      include: { messages: { orderBy: { createdAt: 'asc' } } },
-    })) as ConversationRow & { messages: any[] };
+      // Deliberately NOT `include: { messages: ... }` — that loaded every
+      // message in the thread on every send just to read back the one we had in
+      // hand.
+    })) as ConversationRow;
 
+    const messageDto = await this.toMessageDto({
+      ...(message as MessageRow),
+      attachments: stored,
+    });
     const dto = this.toConversationDto(updated, 0);
-    this.gateway.emitMessage(this.ownerRoom(updated), dto, this.toMessageDto(message));
-    return { conversation: updated, message };
+    this.gateway.emitMessage(this.ownerRoom(updated), dto, messageDto);
+    return { conversation: updated, message: messageDto };
+  }
+
+  /**
+   * Push bytes to MinIO, then record them. Object keys are namespaced by message
+   * id and the stored name is sanitized so the key survives the round-trip
+   * through its own URL (spaces/unicode would otherwise percent-encode and no
+   * longer match the key).
+   */
+  private async storeAttachments(
+    messageId: string,
+    files: Express.Multer.File[],
+  ): Promise<AttachmentRow[]> {
+    return Promise.all(
+      files.map(async (file) => {
+        const safeName = file.originalname
+          .normalize('NFKD')
+          .replace(/[^\w.\-]+/g, '_')
+          .replace(/_{2,}/g, '_')
+          .replace(/^_+|_+$/g, '');
+        // The random segment is load-bearing: `Date.now()` is NOT unique across
+        // this batch, since every callback runs to its first await in the same
+        // tick and reads the same millisecond. Two files sharing a name — e.g.
+        // two pasted screenshots, which browsers both call "image.png" — would
+        // otherwise build the same key and silently overwrite each other.
+        const objectName = `support_message/${messageId}/${Date.now()}_${randomUUID().slice(0, 8)}_${safeName}`;
+        const url = await this.minio.uploadFile(objectName, file.buffer, file.mimetype);
+        return this.prisma.supportAttachment.create({
+          data: {
+            messageId,
+            name: file.originalname,
+            mimeType: file.mimetype,
+            size: file.size,
+            url,
+          },
+        });
+      }),
+    );
+  }
+
+  /**
+   * Chat upload rules — kept in step with the freight side via the shared
+   * SUPPORT_ATTACHMENT_* constants. Notably excludes SVG: it's executable markup
+   * and this is a file one user pushes at another.
+   */
+  private assertSendable(text: string, attachments: Express.Multer.File[]): void {
+    if (!text && attachments.length === 0) {
+      throw new BadRequestException('A message needs text or at least one attachment.');
+    }
+    if (attachments.length > SUPPORT_ATTACHMENT_MAX_PER_MESSAGE) {
+      throw new BadRequestException(
+        `At most ${SUPPORT_ATTACHMENT_MAX_PER_MESSAGE} files per message.`,
+      );
+    }
+    for (const file of attachments) {
+      if (!isSupportAttachmentAllowed(file.mimetype)) {
+        throw new BadRequestException(`Unsupported attachment type: ${file.mimetype}`);
+      }
+      if (file.size > SUPPORT_ATTACHMENT_MAX_BYTES) {
+        throw new BadRequestException(
+          `"${file.originalname}" exceeds the ${
+            SUPPORT_ATTACHMENT_MAX_BYTES / (1024 * 1024)
+          }MB attachment limit.`,
+        );
+      }
+    }
+  }
+
+  /** Inbox preview line — falls back to filenames when there's no text. */
+  private buildPreview(text: string, attachments: AttachmentRow[]): string {
+    if (text) return text.slice(0, 280);
+    if (attachments.length === 1) {
+      return `${ATTACHMENT_ONLY_PREVIEW} ${attachments[0].name}`.slice(0, 280);
+    }
+    return `${ATTACHMENT_ONLY_PREVIEW} ${attachments.length} files`;
   }
 
   private async buildListResult(
@@ -340,9 +523,7 @@ export class SupportService {
     side: Side,
   ): Promise<T.PassengerSupportConversationListResult> {
     const unreadMap = await this.computeUnread(rows, side);
-    const items = rows.map((r) =>
-      this.toConversationDto(r, unreadMap.get(r.id) ?? 0),
-    );
+    const items = rows.map((r) => this.toConversationDto(r, unreadMap.get(r.id) ?? 0));
     let unreadCount = 0;
     for (const n of unreadMap.values()) if (n > 0) unreadCount++;
     return { items, count, unreadCount };
@@ -365,10 +546,7 @@ export class SupportService {
       select: { conversationId: true, createdAt: true },
     });
     const cursorById = new Map(
-      rows.map((r) => [
-        r.id,
-        side === 'USER' ? r.userLastReadAt : r.agentLastReadAt,
-      ]),
+      rows.map((r) => [r.id, side === 'USER' ? r.userLastReadAt : r.agentLastReadAt]),
     );
     for (const m of msgs) {
       const cursor = cursorById.get(m.conversationId) ?? null;
@@ -448,27 +626,75 @@ export class SupportService {
     };
   }
 
-  private toMessageDto(m: {
-    id: string;
-    conversationId: string;
-    sender: PrismaSender;
-    text: string;
-    createdAt: Date;
-  }): T.PassengerSupportMessageDto {
+  private async toMessageDto(m: MessageRow): Promise<T.PassengerSupportMessageDto> {
     return {
       id: m.id,
       conversationId: m.conversationId,
       sender: this.toDtoSender(m.sender) ?? T.PassengerSupportSender.AGENT,
-      text: m.text,
+      text: m.text ?? '',
+      attachments: (m.attachments ?? []).map((a) => this.toAttachmentDto(a)),
       createdAt: m.createdAt.toISOString(),
     };
   }
 
+  /**
+   * Where the client fetches the bytes: this API's own stream route, NOT a
+   * presigned MinIO URL. Presigned object URLs are not reachable from the
+   * browser in this deployment, which is why every working file in the platform
+   * streams through the API instead.
+   *
+   * The path is audience-independent on purpose. A new message is pushed over
+   * the socket to the device room *and* the backoffice room in one payload, so a
+   * URL that embedded the caller's identity (a `?deviceId=`, say) would be wrong
+   * for one of the two recipients.
+   *
+   * The client can't use this path as an `<img src>` either — the agent side's
+   * guard only reads a bearer header, which an image request can't send — so the
+   * web apps fetch it through their authenticated client and render a blob.
+   */
+  private toAttachmentDto(a: AttachmentRow): T.PassengerSupportAttachmentDto {
+    return {
+      id: a.id,
+      name: a.name,
+      mimeType: a.mimeType,
+      size: a.size,
+      url: `/support/attachments/${a.id}`,
+    };
+  }
+
+  /**
+   * Bytes for a chat attachment.
+   *
+   * Deliberately unscoped, and this is a trade-off worth naming: passenger
+   * support threads are already reachable by whoever holds the device/guest id
+   * (see the device routes — "anyone with the device id can see that thread",
+   * the accepted MVP posture), and the agent routes admit any authenticated
+   * caller pending real staff gating. Scoping this endpoint tighter than the
+   * thread it belongs to would buy nothing, so it matches that posture: the
+   * attachment UUID is the capability.
+   *
+   * TODO: tighten alongside the agent-route staff permission — at that point
+   * both the thread and its attachments should be gated the same way.
+   */
+  async streamAttachment(
+    fileId: string,
+  ): Promise<{ stream: Readable; mimeType: string; name: string }> {
+    const attachment = await this.prisma.supportAttachment.findUnique({
+      where: { id: fileId },
+    });
+    if (!attachment) throw new NotFoundException('Attachment not found');
+
+    const objectName = this.minio.getObjectNameFromUrl(attachment.url);
+    return {
+      stream: await this.minio.getFileStream(objectName),
+      mimeType: attachment.mimeType,
+      name: attachment.name,
+    };
+  }
+
   /** Legacy BOT messages are surfaced as AGENT to the UI. */
   private toDtoSender(s: PrismaSender | null): T.PassengerSupportSender | null {
     if (!s) return null;
-    return s === 'USER'
-      ? T.PassengerSupportSender.USER
-      : T.PassengerSupportSender.AGENT;
+    return s === 'USER' ? T.PassengerSupportSender.USER : T.PassengerSupportSender.AGENT;
   }
 }

From 4b4a4ce78834c1e6cd1a291e45a1def6ca9ac3a3 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 18 Jul 2026 09:44:33 +0000
Subject: [PATCH 07/15] feat: setup the attachment to the passenger clients

---
 .../backoffice/src/app/support/page.tsx       | 300 ++++++++++++++----
 .../features/support/AttachmentDraftBar.tsx   |  59 ++++
 .../features/support/MessageAttachments.tsx   | 105 ++++++
 .../src/features/support/supportApi.ts        |  76 ++++-
 .../features/support/useAttachmentDraft.ts    | 123 +++++++
 .../support/useAttachmentObjectUrl.ts         |  79 +++++
 .../src/features/support/useFilePreview.tsx   |  82 +++++
 .../src/features/support/useSupport.ts        | 157 ++++++++-
 .../src/features/support/useSupportSocket.ts  |  48 +--
 .../backoffice/src/lib/api-client.ts          |  11 +-
 .../features/support/AttachmentDraftBar.tsx   |  59 ++++
 .../src/features/support/ImagePreview.tsx     |  73 +++++
 .../features/support/MessageAttachments.tsx   | 108 +++++++
 .../src/features/support/SupportPanel.tsx     | 238 ++++++++++++--
 .../src/features/support/SupportWidget.tsx    |  23 +-
 .../portal/src/features/support/supportApi.ts |  75 ++++-
 .../features/support/useAttachmentDraft.ts    | 123 +++++++
 .../support/useAttachmentObjectUrl.ts         |  79 +++++
 .../portal/src/features/support/useSupport.ts | 134 +++++++-
 .../src/features/support/useSupportSocket.ts  |  61 ++--
 20 files changed, 1832 insertions(+), 181 deletions(-)
 create mode 100644 apps/edr-passenger-web/backoffice/src/features/support/AttachmentDraftBar.tsx
 create mode 100644 apps/edr-passenger-web/backoffice/src/features/support/MessageAttachments.tsx
 create mode 100644 apps/edr-passenger-web/backoffice/src/features/support/useAttachmentDraft.ts
 create mode 100644 apps/edr-passenger-web/backoffice/src/features/support/useAttachmentObjectUrl.ts
 create mode 100644 apps/edr-passenger-web/backoffice/src/features/support/useFilePreview.tsx
 create mode 100644 apps/edr-passenger-web/portal/src/features/support/AttachmentDraftBar.tsx
 create mode 100644 apps/edr-passenger-web/portal/src/features/support/ImagePreview.tsx
 create mode 100644 apps/edr-passenger-web/portal/src/features/support/MessageAttachments.tsx
 create mode 100644 apps/edr-passenger-web/portal/src/features/support/useAttachmentDraft.ts
 create mode 100644 apps/edr-passenger-web/portal/src/features/support/useAttachmentObjectUrl.ts

diff --git a/apps/edr-passenger-web/backoffice/src/app/support/page.tsx b/apps/edr-passenger-web/backoffice/src/app/support/page.tsx
index 246a6f4f9..3e1156818 100644
--- a/apps/edr-passenger-web/backoffice/src/app/support/page.tsx
+++ b/apps/edr-passenger-web/backoffice/src/app/support/page.tsx
@@ -1,9 +1,14 @@
 'use client';
 
-import { Passenger } from '@edr/types';
-import { Headset, Search, Send, User } from 'lucide-react';
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { Passenger, SUPPORT_ATTACHMENT_ACCEPT } from '@edr/types';
+import { Headset, Paperclip, Search, Send, User, X } from 'lucide-react';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 
+import { AttachmentDraftBar } from '@/features/support/AttachmentDraftBar';
+import { MessageAttachments } from '@/features/support/MessageAttachments';
+import { useAttachmentDraft } from '@/features/support/useAttachmentDraft';
+import { useLazyAttachmentObjectUrl } from '@/features/support/useAttachmentObjectUrl';
+import { useFilePreview } from '@/features/support/useFilePreview';
 import {
   useConversations,
   useMarkRead,
@@ -16,6 +21,10 @@ import { useSupportSocket } from '@/features/support/useSupportSocket';
 const GREEN = 'rgb(20 113 76)';
 type ConversationDto = Passenger.PassengerSupportConversationDto;
 type MessageDto = Passenger.PassengerSupportMessageDto;
+type AttachmentDto = Passenger.PassengerSupportAttachmentDto;
+
+/** Distance from an edge (px) that counts as "at" it. */
+const SCROLL_EDGE_SLOP = 120;
 
 const STATUS_CLASS: Record<string, string> = {
   OPEN: 'bg-emerald-100 text-emerald-700 dark:bg-emerald-900/40 dark:text-emerald-300',
@@ -39,10 +48,9 @@ export default function SupportPage() {
   const [search, setSearch] = useState('');
   const [selectedId, setSelectedId] = useState<string | null>(null);
 
-  const { data, isLoading } = useConversations(
+  const { items, isLoading, hasNextPage, isFetchingNextPage, fetchNextPage } = useConversations(
     status === 'ALL' ? { search } : { status, search },
   );
-  const items = useMemo(() => data?.items ?? [], [data?.items]);
 
   useSupportSocket(true);
 
@@ -51,6 +59,17 @@ export default function SupportPage() {
     [items, selectedId],
   );
 
+  // Pull the next page in as the agent nears the end of the list. The list
+  // previously rendered a single fetch, so any thread past the server's default
+  // page was simply unreachable.
+  const onInboxScroll = (e: React.UIEvent<HTMLDivElement>) => {
+    if (!hasNextPage || isFetchingNextPage) return;
+    const el = e.currentTarget;
+    if (el.scrollHeight - el.scrollTop - el.clientHeight < SCROLL_EDGE_SLOP) {
+      fetchNextPage();
+    }
+  };
+
   return (
     <div className="space-y-4">
       <div className="flex items-center gap-3">
@@ -73,10 +92,7 @@ export default function SupportPage() {
         <div className="flex w-[340px] shrink-0 flex-col border-r border-border">
           <div className="space-y-2 border-b border-border p-3">
             <div className="relative">
-              <Search
-                size={16}
-                className="absolute left-3 top-2.5 text-muted-foreground"
-              />
+              <Search size={16} className="absolute left-3 top-2.5 text-muted-foreground" />
               <input
                 value={search}
                 onChange={(e) => setSearch(e.target.value)}
@@ -90,9 +106,7 @@ export default function SupportPage() {
                   key={f}
                   onClick={() => setStatus(f)}
                   className={`flex-1 rounded-md px-2 py-1 text-xs font-medium capitalize transition ${
-                    status === f
-                      ? 'text-white'
-                      : 'bg-muted text-muted-foreground hover:bg-muted/70'
+                    status === f ? 'text-white' : 'bg-muted text-muted-foreground hover:bg-muted/70'
                   }`}
                   style={status === f ? { background: GREEN } : undefined}
                 >
@@ -101,24 +115,25 @@ export default function SupportPage() {
               ))}
             </div>
           </div>
-          <div className="flex-1 overflow-y-auto">
+          <div className="flex-1 overflow-y-auto" onScroll={onInboxScroll}>
             {isLoading ? (
-              <div className="p-6 text-center text-sm text-muted-foreground">
-                Loading…
-              </div>
+              <div className="p-6 text-center text-sm text-muted-foreground">Loading…</div>
             ) : items.length === 0 ? (
-              <div className="p-6 text-center text-sm text-muted-foreground">
-                No conversations.
-              </div>
+              <div className="p-6 text-center text-sm text-muted-foreground">No conversations.</div>
             ) : (
-              items.map((c) => (
-                <InboxRow
-                  key={c.id}
-                  c={c}
-                  active={c.id === selectedId}
-                  onClick={() => setSelectedId(c.id)}
-                />
-              ))
+              <>
+                {items.map((c) => (
+                  <InboxRow
+                    key={c.id}
+                    c={c}
+                    active={c.id === selectedId}
+                    onClick={() => setSelectedId(c.id)}
+                  />
+                ))}
+                {isFetchingNextPage && (
+                  <div className="p-3 text-center text-xs text-muted-foreground">Loading more…</div>
+                )}
+              </>
             )}
           </div>
         </div>
@@ -160,7 +175,9 @@ function InboxRow({
       className={`block w-full border-b border-border px-4 py-3 text-left transition hover:bg-muted/50 ${
         active ? 'bg-muted/70' : ''
       }`}
-      style={active ? { borderLeft: `3px solid ${GREEN}` } : { borderLeft: '3px solid transparent' }}
+      style={
+        active ? { borderLeft: `3px solid ${GREEN}` } : { borderLeft: '3px solid transparent' }
+      }
     >
       <div className="flex items-center justify-between gap-2">
         <span
@@ -204,31 +221,131 @@ function InboxRow({
 }
 
 function ConversationThread({ conversation }: { conversation: ConversationDto }) {
-  const { data: messages, isLoading } = useMessages(conversation.id);
+  const { messages, pageCount, isLoading, hasNextPage, isFetchingNextPage, fetchNextPage } =
+    useMessages(conversation.id);
   const send = useSendMessage(conversation.id);
   const setStatus = useSetStatus();
   const markRead = useMarkRead();
   const [draft, setDraft] = useState('');
+  const [dragging, setDragging] = useState(false);
+  const [error, setError] = useState<string | null>(null);
   const viewport = useRef<HTMLDivElement>(null);
+  const fileInput = useRef<HTMLInputElement>(null);
+  const { view, viewer } = useFilePreview();
+  const attach = useAttachmentDraft(setError);
+  const loadAttachment = useLazyAttachmentObjectUrl();
+
+  /**
+   * Scroll height captured just before an older page was requested, tagged with
+   * the page count at that moment.
+   *
+   * The page count is what makes this safe. Keyed on presence alone, a message
+   * arriving over the socket while history was still in flight would consume the
+   * snapshot on a one-bubble append, and the real 30-message prepend would then
+   * land with nothing to correct against — throwing the reader exactly as far as
+   * this exists to prevent. Comparing counts means only an actual new page can
+   * claim it.
+   */
+  const pendingRestore = useRef<{ height: number; atPageCount: number } | null>(null);
+  /** Whether the agent is parked at the bottom and wants to follow new messages. */
+  const stick = useRef(true);
+  /** Which thread the refs above describe; a switch resets them. */
+  const anchoredThread = useRef(conversation.id);
+
+  const messageCount = messages.length;
 
   useEffect(() => {
     markRead.mutate(conversation.id);
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [conversation.id, messages?.length]);
+  }, [conversation.id, messageCount]);
 
+  // A send failure belongs to the thread it was typed in, not the next one.
   useEffect(() => {
-    viewport.current?.scrollTo({ top: viewport.current.scrollHeight });
-  }, [messages?.length, conversation.id]);
+    setError(null);
+  }, [conversation.id]);
+
+  /**
+   * Keep the viewport sensible as the list changes underneath it.
+   *
+   * Two different things change `messages`, and they want opposite behaviour:
+   * a new message at the bottom should follow (if the agent is already there),
+   * while an older page prepended at the top must NOT move the content the
+   * agent is reading. Layout effect, not effect — this has to run before paint
+   * or the prepend visibly jumps.
+   */
+  useLayoutEffect(() => {
+    const el = viewport.current;
+    if (!el) return;
+
+    // Thread switch: start a fresh read at the bottom and drop the previous
+    // thread's anchoring state.
+    if (anchoredThread.current !== conversation.id) {
+      anchoredThread.current = conversation.id;
+      pendingRestore.current = null;
+      stick.current = true;
+      el.scrollTo({ top: el.scrollHeight });
+      return;
+    }
+
+    const restore = pendingRestore.current;
+    if (restore && pageCount > restore.atPageCount) {
+      // An older page went in above: push the scroll down by exactly the height
+      // that was added, so the same message stays under the cursor.
+      el.scrollTop += el.scrollHeight - restore.height;
+      pendingRestore.current = null;
+      return;
+    }
+    if (stick.current) el.scrollTo({ top: el.scrollHeight });
+  }, [messages, pageCount, conversation.id]);
+
+  const onScroll = (e: React.UIEvent<HTMLDivElement>) => {
+    const el = e.currentTarget;
+    stick.current = el.scrollHeight - el.scrollTop - el.clientHeight < SCROLL_EDGE_SLOP;
+    if (el.scrollTop < SCROLL_EDGE_SLOP && hasNextPage && !isFetchingNextPage) {
+      // A failed fetch leaves this set, which is harmless: the list didn't
+      // change, so the height is still accurate for the retry, and the count
+      // tag stops it being mistaken for a landed page in the meantime.
+      pendingRestore.current = {
+        height: el.scrollHeight,
+        atPageCount: pageCount,
+      };
+      fetchNextPage();
+    }
+  };
 
   const submit = async () => {
     const text = draft.trim();
-    if (!text) return;
+    if (!text && attach.attachments.length === 0) return;
+    const files = attach.files;
+    // Clear optimistically so the composer feels instant; on failure the text
+    // is restored below rather than silently lost.
     setDraft('');
-    await send.mutateAsync(text);
+    attach.clear();
+    setError(null);
+    stick.current = true;
+    try {
+      await send.mutateAsync({ text: text || undefined, attachments: files });
+    } catch (err) {
+      setDraft(text);
+      setError(err instanceof Error ? err.message : "Couldn't send that message.");
+    }
   };
 
-  const changeStatus = (status: string) =>
-    setStatus.mutate({ id: conversation.id, status });
+  const changeStatus = (status: string) => setStatus.mutate({ id: conversation.id, status });
+
+  // Images already hold their bytes as an object URL from rendering the
+  // thumbnail, so reuse it rather than fetching the same file twice.
+  const openAttachment = (a: AttachmentDto, src: string) =>
+    view({ name: a.name, url: src, mimeType: a.mimeType });
+
+  // Documents aren't fetched until opened.
+  const openFile = async (a: AttachmentDto) => {
+    try {
+      view({ name: a.name, url: await loadAttachment(a.url), mimeType: a.mimeType });
+    } catch {
+      setError(`Couldn't open ${a.name}.`);
+    }
+  };
 
   return (
     <div className="flex h-full flex-col">
@@ -282,21 +399,85 @@ function ConversationThread({ conversation }: { conversation: ConversationDto })
         </div>
       </div>
 
-      <div ref={viewport} className="flex-1 space-y-3 overflow-y-auto p-4">
+      <div ref={viewport} onScroll={onScroll} className="flex-1 space-y-3 overflow-y-auto p-4">
         {isLoading ? (
-          <div className="p-6 text-center text-sm text-muted-foreground">
-            Loading…
-          </div>
+          <div className="p-6 text-center text-sm text-muted-foreground">Loading…</div>
+        ) : messages.length === 0 ? (
+          <div className="p-6 text-center text-sm text-muted-foreground">No messages yet.</div>
         ) : (
-          (messages ?? []).map((m) => <AgentBubble key={m.id} m={m} />)
+          <>
+            {isFetchingNextPage && (
+              <div className="py-2 text-center text-xs text-muted-foreground">
+                Loading earlier messages…
+              </div>
+            )}
+            {!hasNextPage && (
+              <div className="text-center text-[10px] text-muted-foreground">
+                Start of conversation
+              </div>
+            )}
+            {messages.map((m) => (
+              <AgentBubble key={m.id} m={m} onView={openAttachment} onOpenFile={openFile} />
+            ))}
+          </>
         )}
       </div>
 
-      <div className="border-t border-border p-3">
+      <div
+        className={`border-t border-border p-3 ${
+          dragging
+            ? 'bg-emerald-50 outline-dashed outline-2 -outline-offset-4 outline-emerald-600 dark:bg-emerald-900/20'
+            : ''
+        }`}
+        onDragOver={(e) => {
+          e.preventDefault();
+          setDragging(true);
+        }}
+        onDragLeave={() => setDragging(false)}
+        onDrop={(e) => {
+          e.preventDefault();
+          setDragging(false);
+          attach.add(Array.from(e.dataTransfer.files));
+        }}
+      >
+        {error && (
+          <div className="mb-2 flex items-center justify-between gap-2 rounded-lg bg-red-100 px-3 py-1.5 text-xs text-red-700 dark:bg-red-900/40 dark:text-red-300">
+            <span>{error}</span>
+            <button onClick={() => setError(null)} aria-label="Dismiss">
+              <X size={12} />
+            </button>
+          </div>
+        )}
+        <AttachmentDraftBar attachments={attach.attachments} onRemove={attach.remove} />
         <div className="flex items-end gap-2">
+          <input
+            ref={fileInput}
+            type="file"
+            multiple
+            accept={SUPPORT_ATTACHMENT_ACCEPT}
+            hidden
+            onChange={(e) => {
+              attach.add(Array.from(e.currentTarget.files ?? []));
+              // Reset so picking the same file twice in a row still fires change.
+              e.currentTarget.value = '';
+            }}
+          />
+          <button
+            onClick={() => fileInput.current?.click()}
+            aria-label="Attach files"
+            className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg text-muted-foreground transition hover:bg-muted"
+          >
+            <Paperclip size={18} />
+          </button>
           <textarea
             value={draft}
             onChange={(e) => setDraft(e.target.value)}
+            // Screenshots land on the clipboard as files. Take them and
+            // suppress the default, which would otherwise also paste the
+            // image's name (or nothing) as text.
+            onPaste={(e) => {
+              if (attach.addFromPaste(e.clipboardData)) e.preventDefault();
+            }}
             onKeyDown={(e) => {
               if (e.key === 'Enter' && !e.shiftKey) {
                 e.preventDefault();
@@ -304,12 +485,12 @@ function ConversationThread({ conversation }: { conversation: ConversationDto })
               }
             }}
             rows={1}
-            placeholder="Type your reply…  (Enter to send, Shift+Enter for newline)"
+            placeholder="Type your reply, or paste an image…  (Enter to send, Shift+Enter for newline)"
             className="max-h-28 flex-1 resize-none rounded-lg border border-border bg-background px-3 py-2 text-sm outline-none focus:border-emerald-500"
           />
           <button
             onClick={submit}
-            disabled={!draft.trim() || send.isPending}
+            disabled={(!draft.trim() && attach.attachments.length === 0) || send.isPending}
             className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg text-white transition hover:opacity-90 disabled:opacity-50"
             style={{ background: GREEN }}
             aria-label="Send"
@@ -318,11 +499,20 @@ function ConversationThread({ conversation }: { conversation: ConversationDto })
           </button>
         </div>
       </div>
+      {viewer}
     </div>
   );
 }
 
-function AgentBubble({ m }: { m: MessageDto }) {
+function AgentBubble({
+  m,
+  onView,
+  onOpenFile,
+}: {
+  m: MessageDto;
+  onView: (a: AttachmentDto, src: string) => void;
+  onOpenFile: (a: AttachmentDto) => void;
+}) {
   const mine = m.sender === 'AGENT';
   return (
     <div className={`flex ${mine ? 'justify-end' : 'justify-start'} items-end gap-2`}>
@@ -332,22 +522,22 @@ function AgentBubble({ m }: { m: MessageDto }) {
         </span>
       )}
       <div className="max-w-[70%]">
-        <p
-          className={`mb-0.5 text-xs text-muted-foreground ${
-            mine ? 'text-right' : 'text-left'
-          }`}
-        >
+        <p className={`mb-0.5 text-xs text-muted-foreground ${mine ? 'text-right' : 'text-left'}`}>
           {mine ? m.authorName || 'You' : m.authorName || 'Passenger'}
         </p>
         <div
-          className={`whitespace-pre-wrap break-words rounded-2xl px-3 py-2 text-sm ${
-            mine
-              ? 'rounded-br-sm text-white'
-              : 'rounded-bl-sm bg-muted text-foreground'
+          className={`rounded-2xl px-3 py-2 text-sm ${
+            mine ? 'rounded-br-sm text-white' : 'rounded-bl-sm bg-muted text-foreground'
           }`}
           style={mine ? { background: GREEN } : undefined}
         >
-          {m.text}
+          {m.text && <p className="whitespace-pre-wrap break-words">{m.text}</p>}
+          <MessageAttachments
+            attachments={m.attachments}
+            mine={mine}
+            onView={onView}
+            onOpenFile={onOpenFile}
+          />
         </div>
         <p
           className={`mt-0.5 text-[10px] text-muted-foreground ${
diff --git a/apps/edr-passenger-web/backoffice/src/features/support/AttachmentDraftBar.tsx b/apps/edr-passenger-web/backoffice/src/features/support/AttachmentDraftBar.tsx
new file mode 100644
index 000000000..eca0722f7
--- /dev/null
+++ b/apps/edr-passenger-web/backoffice/src/features/support/AttachmentDraftBar.tsx
@@ -0,0 +1,59 @@
+'use client';
+
+import { FileText, X } from 'lucide-react';
+
+import { formatBytes } from './MessageAttachments';
+import type { PendingAttachment } from './useAttachmentDraft';
+
+/**
+ * The staged-files strip above the composer. Shows what will be sent and lets
+ * the agent drop any of it before hitting send.
+ */
+export function AttachmentDraftBar({
+  attachments,
+  onRemove,
+}: {
+  attachments: PendingAttachment[];
+  onRemove: (id: string) => void;
+}) {
+  if (attachments.length === 0) return null;
+
+  return (
+    <div className="mb-2 flex flex-wrap gap-2">
+      {attachments.map((a) => (
+        <div
+          key={a.id}
+          className="relative flex items-center gap-1.5 rounded-lg border border-border bg-background p-1 pr-4"
+        >
+          {a.previewUrl ? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={a.previewUrl}
+              alt={a.file.name}
+              className="h-9 w-9 shrink-0 rounded object-cover"
+            />
+          ) : (
+            <span className="flex h-9 w-9 shrink-0 items-center justify-center rounded bg-muted text-muted-foreground">
+              <FileText size={16} />
+            </span>
+          )}
+          <span className="min-w-0 max-w-[120px]">
+            <span className="block truncate text-xs font-semibold text-foreground">
+              {a.file.name}
+            </span>
+            <span className="block text-[10px] text-muted-foreground">
+              {formatBytes(a.file.size)}
+            </span>
+          </span>
+          <button
+            onClick={() => onRemove(a.id)}
+            aria-label={`Remove ${a.file.name}`}
+            className="absolute -right-1.5 -top-1.5 flex h-4 w-4 items-center justify-center rounded-full bg-gray-600 text-white transition hover:bg-gray-700"
+          >
+            <X size={10} />
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/edr-passenger-web/backoffice/src/features/support/MessageAttachments.tsx b/apps/edr-passenger-web/backoffice/src/features/support/MessageAttachments.tsx
new file mode 100644
index 000000000..5e7bda600
--- /dev/null
+++ b/apps/edr-passenger-web/backoffice/src/features/support/MessageAttachments.tsx
@@ -0,0 +1,105 @@
+'use client';
+
+import { isSupportAttachmentImage, type Passenger } from '@edr/types';
+import { FileText, ImageOff } from 'lucide-react';
+
+import { useAttachmentObjectUrl } from './useAttachmentObjectUrl';
+
+type AttachmentDto = Passenger.PassengerSupportAttachmentDto;
+
+/** Human-readable size — kept coarse; nobody needs bytes in a chat bubble. */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * One image attachment. Its own component because the bytes are fetched through
+ * the authenticated client (see {@link useAttachmentObjectUrl}) and a hook can't
+ * be called from inside a `.map()`.
+ */
+function ImageAttachment({
+  a,
+  onView,
+}: {
+  a: AttachmentDto;
+  onView: (a: AttachmentDto, src: string) => void;
+}) {
+  const { src, failed } = useAttachmentObjectUrl(a.url);
+
+  if (failed) {
+    return (
+      <span className="flex items-center gap-1.5 text-xs opacity-75">
+        <ImageOff size={14} className="shrink-0" />
+        Couldn&apos;t load {a.name}
+      </span>
+    );
+  }
+
+  if (!src) {
+    return (
+      <div className="h-[120px] w-[200px] animate-pulse rounded-lg bg-black/10 dark:bg-white/10" />
+    );
+  }
+
+  return (
+    <button
+      onClick={() => onView(a, src)}
+      className="cursor-zoom-in overflow-hidden rounded-lg"
+      aria-label={`View ${a.name}`}
+    >
+      {/* eslint-disable-next-line @next/next/no-img-element */}
+      <img
+        src={src}
+        alt={a.name}
+        // Cap the bubble: a tall screenshot would otherwise push the
+        // whole conversation off-screen.
+        className="max-h-[220px] max-w-[260px] rounded-lg object-cover"
+      />
+    </button>
+  );
+}
+
+/**
+ * Attachments inside a message bubble: images as thumbnails, everything else as
+ * a labelled file row. Non-images are not fetched until opened — pulling every
+ * document in a thread just to draw a filename would be wasteful.
+ */
+export function MessageAttachments({
+  attachments,
+  mine,
+  onView,
+  onOpenFile,
+}: {
+  attachments: AttachmentDto[];
+  mine: boolean;
+  onView: (a: AttachmentDto, src: string) => void;
+  onOpenFile: (a: AttachmentDto) => void;
+}) {
+  if (attachments.length === 0) return null;
+
+  return (
+    <div className="mt-1.5 flex flex-col gap-1.5">
+      {attachments.map((a) =>
+        isSupportAttachmentImage(a.mimeType) ? (
+          <ImageAttachment key={a.id} a={a} onView={onView} />
+        ) : (
+          <button
+            key={a.id}
+            onClick={() => onOpenFile(a)}
+            className={`flex w-full items-center gap-2 rounded-lg px-2.5 py-1.5 text-left transition hover:opacity-90 ${
+              mine ? 'bg-white/20' : 'border border-border bg-background'
+            }`}
+          >
+            <FileText size={16} className="shrink-0" />
+            <span className="min-w-0">
+              <span className="block truncate text-xs font-semibold">{a.name}</span>
+              <span className="block text-[10px] opacity-75">{formatBytes(a.size)}</span>
+            </span>
+          </button>
+        ),
+      )}
+    </div>
+  );
+}
diff --git a/apps/edr-passenger-web/backoffice/src/features/support/supportApi.ts b/apps/edr-passenger-web/backoffice/src/features/support/supportApi.ts
index b6fac65bc..963fb3baf 100644
--- a/apps/edr-passenger-web/backoffice/src/features/support/supportApi.ts
+++ b/apps/edr-passenger-web/backoffice/src/features/support/supportApi.ts
@@ -5,32 +5,78 @@ import { apiClient } from '@/lib/api-client';
 type ConversationDto = Passenger.PassengerSupportConversationDto;
 type MessageDto = Passenger.PassengerSupportMessageDto;
 type ListResult = Passenger.PassengerSupportConversationListResult;
+type MessageListResult = Passenger.PassengerSupportMessageListResult;
 
 export interface ListParams {
   status?: string;
   search?: string;
+  page?: number;
+  limit?: number;
 }
 
+export interface ListMessagesParams {
+  /** Opaque cursor from the previous page's `nextCursor`. */
+  before?: string;
+  limit?: number;
+}
+
+/** What the composer hands over: text, files, or both (never neither). */
+export interface SendMessageInput {
+  text?: string;
+  attachments?: File[];
+}
+
+/**
+ * A message with files goes as multipart so the server can persist them against
+ * the message it creates in the same request; text-only stays JSON.
+ */
+function toRequestBody(input: SendMessageInput): FormData | { text?: string } {
+  if (!input.attachments?.length) return { text: input.text };
+
+  const form = new FormData();
+  if (input.text) form.append('text', input.text);
+  for (const file of input.attachments) form.append('attachments', file);
+  return form;
+}
+
+/**
+ * `apiClient` pins `Content-Type: application/json` on every request. Axios
+ * reads that header in `transformRequest` and, seeing JSON, runs FormData
+ * through `formDataToJSON` — the files would be silently dropped and the server
+ * would store an empty message. Clearing the header (rather than setting
+ * `multipart/form-data` by hand, which omits the boundary) is what lets the
+ * browser generate a proper boundary of its own.
+ */
+const multipartConfig = { headers: { 'Content-Type': undefined } };
+
 /** Passenger backoffice (agent) support-chat REST calls (client unwraps envelope). */
 export const supportApi = {
   listConversations: (params: ListParams = {}) =>
     apiClient.get<ListResult>('/support/agent/conversations', { params }),
-  listMessages: (id: string) =>
-    apiClient.get<MessageDto[]>(`/support/agent/conversations/${id}/messages`),
-  sendMessage: (id: string, text: string) =>
-    apiClient.post<MessageDto>(
+  listMessages: (id: string, params: ListMessagesParams = {}) =>
+    apiClient.get<MessageListResult>(`/support/agent/conversations/${id}/messages`, { params }),
+  sendMessage: (id: string, input: SendMessageInput) => {
+    const body = toRequestBody(input);
+    return apiClient.post<MessageDto>(
       `/support/agent/conversations/${id}/messages`,
-      { text },
-    ),
+      body,
+      body instanceof FormData ? multipartConfig : undefined,
+    );
+  },
+  /**
+   * Attachment bytes, fetched through this client so the bearer token rides along
+   * — the guard reads `Authorization` only, so a direct `<img src>` would 401.
+   *
+   * `relativeUrl` is the DTO's `url` (`/support/attachments/:id`); the passenger
+   * API has no global prefix, so it appends to the client's baseURL as-is.
+   */
+  fetchAttachment: async (relativeUrl: string): Promise<Blob> => {
+    const data = await apiClient.getRaw<Blob>(relativeUrl, { responseType: 'blob' });
+    return data;
+  },
   setStatus: (id: string, status: string) =>
-    apiClient.patch<ConversationDto>(
-      `/support/agent/conversations/${id}/status`,
-      { status },
-    ),
+    apiClient.patch<ConversationDto>(`/support/agent/conversations/${id}/status`, { status }),
   markRead: (id: string) =>
-    apiClient.post<{ unreadCount: number }>(
-      `/support/agent/conversations/${id}/read`,
-    ),
-  unreadCount: () =>
-    apiClient.get<{ unreadCount: number }>('/support/agent/unread-count'),
+    apiClient.post<{ unreadCount: number }>(`/support/agent/conversations/${id}/read`),
+  unreadCount: () => apiClient.get<{ unreadCount: number }>('/support/agent/unread-count'),
 };
diff --git a/apps/edr-passenger-web/backoffice/src/features/support/useAttachmentDraft.ts b/apps/edr-passenger-web/backoffice/src/features/support/useAttachmentDraft.ts
new file mode 100644
index 000000000..a3a85c628
--- /dev/null
+++ b/apps/edr-passenger-web/backoffice/src/features/support/useAttachmentDraft.ts
@@ -0,0 +1,123 @@
+'use client';
+
+import {
+  isSupportAttachmentAllowed,
+  isSupportAttachmentImage,
+  SUPPORT_ATTACHMENT_MAX_BYTES,
+  SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+} from '@edr/types';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/** A file staged in the composer, not yet sent. */
+export interface PendingAttachment {
+  /** Local-only id; the server id doesn't exist until the message is sent. */
+  id: string;
+  file: File;
+  /** Object URL, images only. Revoked when the entry goes away. */
+  previewUrl?: string;
+}
+
+let nextId = 0;
+
+/**
+ * Staging area for files being attached to a message.
+ *
+ * Files are held client-side until send, then posted alongside the text in one
+ * multipart request — there's no upload-then-reference step, so nothing to
+ * garbage-collect if the agent changes their mind.
+ *
+ * Object URLs for image previews are revoked on removal and unmount; without
+ * that, pasting screenshots into a long-lived chat page leaks the full bytes of
+ * every image for the life of the tab.
+ */
+export function useAttachmentDraft(onReject?: (reason: string) => void) {
+  const [attachments, setAttachments] = useState<PendingAttachment[]>([]);
+  const rejectRef = useRef(onReject);
+  rejectRef.current = onReject;
+
+  // Read from a ref in the unmount cleanup so it doesn't re-run (and revoke
+  // still-live URLs) on every change to the list.
+  const attachmentsRef = useRef(attachments);
+  attachmentsRef.current = attachments;
+  useEffect(
+    () => () => {
+      for (const a of attachmentsRef.current) {
+        if (a.previewUrl) URL.revokeObjectURL(a.previewUrl);
+      }
+    },
+    [],
+  );
+
+  const add = useCallback((files: File[]) => {
+    if (files.length === 0) return;
+    setAttachments((current) => {
+      const accepted: PendingAttachment[] = [];
+      for (const file of files) {
+        if (current.length + accepted.length >= SUPPORT_ATTACHMENT_MAX_PER_MESSAGE) {
+          rejectRef.current?.(`Up to ${SUPPORT_ATTACHMENT_MAX_PER_MESSAGE} files per message.`);
+          break;
+        }
+        if (!isSupportAttachmentAllowed(file.type)) {
+          rejectRef.current?.(`${file.name}: that file type isn't supported.`);
+          continue;
+        }
+        if (file.size > SUPPORT_ATTACHMENT_MAX_BYTES) {
+          rejectRef.current?.(
+            `${file.name} is over the ${SUPPORT_ATTACHMENT_MAX_BYTES / (1024 * 1024)}MB limit.`,
+          );
+          continue;
+        }
+        accepted.push({
+          id: `pending-${nextId++}`,
+          file,
+          previewUrl: isSupportAttachmentImage(file.type) ? URL.createObjectURL(file) : undefined,
+        });
+      }
+      return accepted.length ? [...current, ...accepted] : current;
+    });
+  }, []);
+
+  const remove = useCallback((id: string) => {
+    setAttachments((current) => {
+      const target = current.find((a) => a.id === id);
+      if (target?.previewUrl) URL.revokeObjectURL(target.previewUrl);
+      return current.filter((a) => a.id !== id);
+    });
+  }, []);
+
+  const clear = useCallback(() => {
+    setAttachments((current) => {
+      for (const a of current) {
+        if (a.previewUrl) URL.revokeObjectURL(a.previewUrl);
+      }
+      return [];
+    });
+  }, []);
+
+  /**
+   * Pull files off a paste. Returns true if anything was taken, so the caller
+   * can suppress the default paste — otherwise pasting a screenshot also drops
+   * its filename (or nothing) into the textarea.
+   *
+   * Copying an image in most apps puts BOTH the bitmap and some text/html on
+   * the clipboard, so check for files first and only then let the text through.
+   */
+  const addFromPaste = useCallback(
+    (clipboard: DataTransfer | null): boolean => {
+      const files = Array.from(clipboard?.files ?? []);
+      if (files.length === 0) return false;
+      add(files);
+      return true;
+    },
+    [add],
+  );
+
+  return {
+    attachments,
+    files: attachments.map((a) => a.file),
+    add,
+    addFromPaste,
+    remove,
+    clear,
+  };
+}
diff --git a/apps/edr-passenger-web/backoffice/src/features/support/useAttachmentObjectUrl.ts b/apps/edr-passenger-web/backoffice/src/features/support/useAttachmentObjectUrl.ts
new file mode 100644
index 000000000..15a80c999
--- /dev/null
+++ b/apps/edr-passenger-web/backoffice/src/features/support/useAttachmentObjectUrl.ts
@@ -0,0 +1,79 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { supportApi } from './supportApi';
+
+/**
+ * Blob object URL for an attachment, or `undefined` while it loads / on failure.
+ *
+ * Chat attachments cannot be rendered with a direct `<img src={a.url}>`. The API
+ * guard takes the bearer token from the `Authorization` header and has no cookie
+ * fallback, and an `<img>` request cannot carry that header — a direct src is an
+ * unavoidable 401. So the bytes are fetched through the authenticated client and
+ * handed to the browser as an object URL.
+ *
+ * The URL is revoked on unmount and whenever the attachment changes, so a thread
+ * scrolled through hundreds of images doesn't pin all of them in memory.
+ */
+export function useAttachmentObjectUrl(relativeUrl: string): {
+  src?: string;
+  failed: boolean;
+} {
+  const [src, setSrc] = useState<string>();
+  const [failed, setFailed] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    let created: string | undefined;
+
+    setSrc(undefined);
+    setFailed(false);
+
+    supportApi
+      .fetchAttachment(relativeUrl)
+      .then((blob) => {
+        // The component may have unmounted mid-flight; creating a URL then would
+        // leak it, since the cleanup below has already run.
+        if (cancelled) return;
+        created = URL.createObjectURL(blob);
+        setSrc(created);
+      })
+      .catch(() => {
+        if (!cancelled) setFailed(true);
+      });
+
+    return () => {
+      cancelled = true;
+      if (created) URL.revokeObjectURL(created);
+    };
+  }, [relativeUrl]);
+
+  return { src, failed };
+}
+
+/**
+ * On-demand variant for files that aren't previewed inline (documents): fetch
+ * only when the user actually opens one, rather than pulling every attachment in
+ * the thread down just to render a filename row.
+ *
+ * Holds a single slot — opening another file revokes the previous URL, as does
+ * unmounting.
+ */
+export function useLazyAttachmentObjectUrl(): (relativeUrl: string) => Promise<string> {
+  const current = useRef<string>();
+
+  useEffect(
+    () => () => {
+      if (current.current) URL.revokeObjectURL(current.current);
+    },
+    [],
+  );
+
+  return useCallback(async (relativeUrl: string) => {
+    const blob = await supportApi.fetchAttachment(relativeUrl);
+    if (current.current) URL.revokeObjectURL(current.current);
+    current.current = URL.createObjectURL(blob);
+    return current.current;
+  }, []);
+}
diff --git a/apps/edr-passenger-web/backoffice/src/features/support/useFilePreview.tsx b/apps/edr-passenger-web/backoffice/src/features/support/useFilePreview.tsx
new file mode 100644
index 000000000..74380ee67
--- /dev/null
+++ b/apps/edr-passenger-web/backoffice/src/features/support/useFilePreview.tsx
@@ -0,0 +1,82 @@
+'use client';
+
+import { isSupportAttachmentImage } from '@edr/types';
+import { Download, ExternalLink, FileText } from 'lucide-react';
+import { useCallback, useState } from 'react';
+
+import Modal from '@/components/ui/Modal';
+
+/** The minimal file shape the preview needs. */
+export interface PreviewableFile {
+  name: string;
+  /**
+   * A blob object URL, not the attachment's API path — the API guard reads the
+   * bearer token from the `Authorization` header, which `<img>` and `<a>` can't
+   * send. Callers fetch the bytes first (see `useAttachmentObjectUrl`).
+   */
+  url: string;
+  mimeType: string;
+}
+
+/**
+ * Drives a single shared preview modal for the page: call `view(file)` from any
+ * attachment, render `viewer` once near the page root.
+ *
+ * Mirrors the shape of `useFileViewer` from `@edr/ui-common`, which the freight
+ * backoffice uses. That hook can't be used here: it renders `@mantine/core`
+ * components, and this app is Tailwind-only with no `MantineProvider` mounted —
+ * its Modal would throw at runtime. Kept deliberately narrow (images inline,
+ * everything else handed to the browser) rather than reimplementing the shared
+ * viewer's pdf/office/video handling; swap this for the shared hook if this app
+ * ever adopts Mantine.
+ */
+export function useFilePreview() {
+  const [file, setFile] = useState<PreviewableFile | null>(null);
+
+  const view = useCallback((f: PreviewableFile) => setFile(f), []);
+  const close = useCallback(() => setFile(null), []);
+
+  const viewer = (
+    <Modal isOpen={file !== null} onClose={close} title={file?.name ?? ''} size="xl">
+      {file && (
+        <div className="flex flex-col items-center gap-4">
+          {isSupportAttachmentImage(file.mimeType) ? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={file.url}
+              alt={file.name}
+              className="max-h-[70vh] w-auto max-w-full rounded-lg object-contain"
+            />
+          ) : (
+            <div className="flex flex-col items-center gap-3 py-10 text-muted-foreground">
+              <FileText size={48} />
+              <p className="text-sm">No inline preview for this file type.</p>
+            </div>
+          )}
+          <div className="flex gap-2">
+            <a
+              href={file.url}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="flex items-center gap-2 rounded-lg border border-border px-3 py-1.5 text-xs font-medium text-foreground transition hover:bg-muted"
+            >
+              <ExternalLink size={14} />
+              Open in new tab
+            </a>
+            <a
+              href={file.url}
+              download={file.name}
+              className="flex items-center gap-2 rounded-lg px-3 py-1.5 text-xs font-medium text-white transition hover:opacity-90"
+              style={{ background: 'rgb(20 113 76)' }}
+            >
+              <Download size={14} />
+              Download
+            </a>
+          </div>
+        </div>
+      )}
+    </Modal>
+  );
+
+  return { view, close, viewer };
+}
diff --git a/apps/edr-passenger-web/backoffice/src/features/support/useSupport.ts b/apps/edr-passenger-web/backoffice/src/features/support/useSupport.ts
index fbe8e7697..85a15c290 100644
--- a/apps/edr-passenger-web/backoffice/src/features/support/useSupport.ts
+++ b/apps/edr-passenger-web/backoffice/src/features/support/useSupport.ts
@@ -1,26 +1,161 @@
 'use client';
 
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import type { Passenger } from '@edr/types';
+import {
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type InfiniteData,
+  type QueryClient,
+} from '@tanstack/react-query';
+import { useMemo } from 'react';
 
-import { supportApi, type ListParams } from './supportApi';
+import { supportApi, type ListParams, type SendMessageInput } from './supportApi';
+
+type MessageDto = Passenger.PassengerSupportMessageDto;
+type MessageListResult = Passenger.PassengerSupportMessageListResult;
 
 export const SUPPORT_CONVERSATIONS_KEY = ['support', 'conversations'];
 export const SUPPORT_UNREAD_KEY = ['support', 'unread'];
 export const supportMessagesKey = (id: string) => ['support', 'messages', id];
 
+/** Threads per page in the inbox. */
+const CONVERSATIONS_PAGE_SIZE = 20;
+/** Messages per page in a thread. */
+const MESSAGES_PAGE_SIZE = 30;
+
+/**
+ * Shared inbox: every thread, filterable by status + subject/passenger search.
+ *
+ * Pages on scroll. This previously fetched one unbounded page and rendered
+ * whatever came back, which silently truncated the inbox at the server's own
+ * default of 100 with no way to reach the rest.
+ */
 export function useConversations(params: ListParams = {}) {
-  return useQuery({
+  const query = useInfiniteQuery({
     queryKey: [...SUPPORT_CONVERSATIONS_KEY, params],
-    queryFn: () => supportApi.listConversations(params),
+    queryFn: ({ pageParam }) =>
+      supportApi.listConversations({
+        ...params,
+        page: pageParam,
+        limit: CONVERSATIONS_PAGE_SIZE,
+      }),
+    initialPageParam: 1,
+    getNextPageParam: (lastPage, allPages) => {
+      const loaded = allPages.reduce((n, page) => n + page.items.length, 0);
+      return loaded < lastPage.count ? allPages.length + 1 : undefined;
+    },
   });
+
+  /**
+   * Flatten for rendering, keeping the page-level fields (count/unreadCount)
+   * from the first fetch so badges don't go stale as more pages load.
+   *
+   * De-duplicated by id because this list pages by OFFSET over a sort key that
+   * moves: a thread jumps to rank 1 the moment it gets a message, shifting
+   * everything down, so a row already shown on page 1 can be served again on
+   * page 2 — and React would then see two children with the same key. The
+   * conversations invalidate that rides along with every such event heals the
+   * ordering a beat later; this just stops the intervening render from breaking.
+   *
+   * Keyset wouldn't help here, unlike the message list: the sort key itself
+   * mutates, so no cursor over it is stable either.
+   */
+  const items = useMemo(() => {
+    const seen = new Set<string>();
+    const flat: Passenger.PassengerSupportConversationDto[] = [];
+    for (const page of query.data?.pages ?? []) {
+      for (const conversation of page.items) {
+        if (seen.has(conversation.id)) continue;
+        seen.add(conversation.id);
+        flat.push(conversation);
+      }
+    }
+    return flat;
+  }, [query.data]);
+
+  return {
+    ...query,
+    items,
+    count: query.data?.pages[0]?.count ?? 0,
+    unreadCount: query.data?.pages[0]?.unreadCount ?? 0,
+  };
 }
 
+/**
+ * A thread's messages, paged backwards from newest.
+ *
+ * react-query's "next page" is *older* history here, so `pages` runs
+ * newest-block-first and has to be reversed to render top-to-bottom in time
+ * order. Cursor-based rather than offset so a message arriving mid-scroll
+ * doesn't shift the pages already loaded.
+ */
 export function useMessages(conversationId: string | null) {
-  return useQuery({
+  const query = useInfiniteQuery({
     queryKey: supportMessagesKey(conversationId ?? ''),
-    queryFn: () => supportApi.listMessages(conversationId as string),
+    queryFn: ({ pageParam }) =>
+      supportApi.listMessages(conversationId as string, {
+        before: pageParam,
+        limit: MESSAGES_PAGE_SIZE,
+      }),
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
     enabled: !!conversationId,
   });
+
+  const messages = useMemo(
+    () => [...(query.data?.pages ?? [])].reverse().flatMap((p) => p.items),
+    [query.data],
+  );
+
+  // Exposed so the view can tell a prepended history page from a message
+  // appended at the bottom — `messages` changing says nothing about which.
+  return { ...query, messages, pageCount: query.data?.pages.length ?? 0 };
+}
+
+/**
+ * Splice a newly-arrived message into a cached thread.
+ *
+ * Deliberately not `invalidateQueries`: that refetches *every* page the agent
+ * has scrolled back through, so the cost of each inbound message would grow
+ * with how far they've read. Page 0 is the newest block and its items are
+ * oldest-first within the block, so the new message belongs on its end.
+ *
+ * No-ops when the thread isn't cached — nothing is rendering it, and seeding a
+ * partial cache here would leave a thread whose "first page" is one message and
+ * whose `nextCursor` is missing.
+ */
+/**
+ * Why this reports an outcome rather than a boolean: the two ways it can decline
+ * to append need opposite handling. A duplicate is the sender's own echo and must
+ * be ignored — refetching there would undo the whole point. "Uncached" means the
+ * thread's first page is still in flight and may have been read on the server
+ * *before* this message existed, so dropping it silently would lose it until
+ * something else happened to refetch; the caller refetches instead. That's cheap
+ * precisely because nothing is loaded yet.
+ */
+export type AppendOutcome = 'appended' | 'duplicate' | 'uncached';
+
+export function appendMessageToCache(qc: QueryClient, message: MessageDto): AppendOutcome {
+  let outcome: AppendOutcome = 'uncached';
+  qc.setQueryData<InfiniteData<MessageListResult>>(
+    supportMessagesKey(message.conversationId),
+    (current) => {
+      if (!current?.pages.length) return current;
+      const [newest, ...rest] = current.pages;
+      if (newest.items.some((m) => m.id === message.id)) {
+        outcome = 'duplicate';
+        return current;
+      }
+      outcome = 'appended';
+      return {
+        ...current,
+        pages: [{ ...newest, items: [...newest.items, message] }, ...rest],
+      };
+    },
+  );
+  return outcome;
 }
 
 export function useUnreadCount(enabled = true) {
@@ -35,9 +170,12 @@ export function useUnreadCount(enabled = true) {
 export function useSendMessage(conversationId: string) {
   const qc = useQueryClient();
   return useMutation({
-    mutationFn: (text: string) => supportApi.sendMessage(conversationId, text),
+    mutationFn: (input: SendMessageInput) => supportApi.sendMessage(conversationId, input),
+    // The gateway echoes our own message back over the socket, which appends it
+    // to the cache — so don't invalidate the thread here or every send would
+    // refetch every page the agent has scrolled through. The conversation list
+    // still needs a refresh for its last-message preview and ordering.
     onSuccess: () => {
-      qc.invalidateQueries({ queryKey: supportMessagesKey(conversationId) });
       qc.invalidateQueries({ queryKey: SUPPORT_CONVERSATIONS_KEY });
     },
   });
@@ -48,8 +186,7 @@ export function useSetStatus() {
   return useMutation({
     mutationFn: ({ id, status }: { id: string; status: string }) =>
       supportApi.setStatus(id, status),
-    onSuccess: () =>
-      qc.invalidateQueries({ queryKey: SUPPORT_CONVERSATIONS_KEY }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: SUPPORT_CONVERSATIONS_KEY }),
   });
 }
 
diff --git a/apps/edr-passenger-web/backoffice/src/features/support/useSupportSocket.ts b/apps/edr-passenger-web/backoffice/src/features/support/useSupportSocket.ts
index aabeb0ce4..15809ef83 100644
--- a/apps/edr-passenger-web/backoffice/src/features/support/useSupportSocket.ts
+++ b/apps/edr-passenger-web/backoffice/src/features/support/useSupportSocket.ts
@@ -6,14 +6,16 @@ import { useEffect, useRef } from 'react';
 import { io } from 'socket.io-client';
 
 import {
+  appendMessageToCache,
   SUPPORT_CONVERSATIONS_KEY,
   SUPPORT_UNREAD_KEY,
   supportMessagesKey,
 } from './useSupport';
 
-const SOCKET_ORIGIN = String(
-  process.env.NEXT_PUBLIC_API_URL || 'http://localhost:4000',
-).replace(/\/api\/?$/, '');
+const SOCKET_ORIGIN = String(process.env.NEXT_PUBLIC_API_URL || 'http://localhost:4000').replace(
+  /\/api\/?$/,
+  '',
+);
 
 /**
  * Subscribes the signed-in agent to live support pushes for the whole shared
@@ -33,37 +35,39 @@ export function useSupportSocket(
     const token = localStorage.getItem('auth_token');
     if (!token) return;
 
-    const socket = io(
-      `${SOCKET_ORIGIN}/${Passenger.PASSENGER_SUPPORT_WS_NAMESPACE}`,
-      {
-        auth: { token },
-        // Prefer WebSocket, fall back to HTTP long-polling if the proxy blocks
-        // the upgrade (polling rides normal HTTPS, already CSP-allowed).
-        transports: ['websocket', 'polling'],
-        withCredentials: true,
-      },
-    );
+    const socket = io(`${SOCKET_ORIGIN}/${Passenger.PASSENGER_SUPPORT_WS_NAMESPACE}`, {
+      auth: { token },
+      // Prefer WebSocket, fall back to HTTP long-polling if the proxy blocks
+      // the upgrade (polling rides normal HTTPS, already CSP-allowed).
+      transports: ['websocket', 'polling'],
+      withCredentials: true,
+    });
 
     // Temporary diagnostics — remove once live delivery is confirmed.
-    socket.on('connect', () =>
-      console.warn('[support] agent socket connected', socket.id),
-    );
+    socket.on('connect', () => console.warn('[support] agent socket connected', socket.id));
     socket.on('connect_error', (err) =>
       console.warn('[support] agent socket connect_error:', err.message),
     );
     socket.on('disconnect', (reason) =>
       console.warn('[support] agent socket disconnected:', reason),
     );
-    socket.on('support:hello', (info) =>
-      console.warn('[support] server assigned:', info),
-    );
+    socket.on('support:hello', (info) => console.warn('[support] server assigned:', info));
 
     socket.on(
       Passenger.PASSENGER_SUPPORT_WS_EVENTS.MESSAGE_NEW,
       (event: Passenger.PassengerSupportMessageEvent) => {
-        qc.invalidateQueries({
-          queryKey: supportMessagesKey(event.message.conversationId),
-        });
+        // Append rather than invalidate: the thread is paginated, and
+        // invalidating it would refetch every page the agent has scrolled back
+        // through on every single inbound message.
+        if (appendMessageToCache(qc, event.message) === 'uncached') {
+          // The thread's first page is still loading and may have been read
+          // before this message existed — without this it would go missing
+          // until some unrelated refetch. Cheap: there are no pages to
+          // re-fetch yet.
+          qc.invalidateQueries({
+            queryKey: supportMessagesKey(event.message.conversationId),
+          });
+        }
         qc.invalidateQueries({ queryKey: SUPPORT_CONVERSATIONS_KEY });
         qc.invalidateQueries({ queryKey: SUPPORT_UNREAD_KEY });
         onMessageRef.current?.(event);
diff --git a/apps/edr-passenger-web/backoffice/src/lib/api-client.ts b/apps/edr-passenger-web/backoffice/src/lib/api-client.ts
index 8d535b71c..d3f1ac21c 100644
--- a/apps/edr-passenger-web/backoffice/src/lib/api-client.ts
+++ b/apps/edr-passenger-web/backoffice/src/lib/api-client.ts
@@ -31,7 +31,7 @@ class ApiClient {
           }
         }
         return Promise.reject(error);
-      }
+      },
     );
   }
 
@@ -40,6 +40,15 @@ class ApiClient {
     return response.data.data;
   }
 
+  /**
+   * GET without the `{ success, data }` unwrap. Binary endpoints (file streams)
+   * have no envelope to unwrap, so `get` would hand back `undefined`.
+   */
+  async getRaw<T>(url: string, config?: AxiosRequestConfig): Promise<T> {
+    const response = await this.client.get<T>(url, config);
+    return response.data;
+  }
+
   async post<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T> {
     const response = await this.client.post<{ success: boolean; data: T }>(url, data, config);
     return response.data.data;
diff --git a/apps/edr-passenger-web/portal/src/features/support/AttachmentDraftBar.tsx b/apps/edr-passenger-web/portal/src/features/support/AttachmentDraftBar.tsx
new file mode 100644
index 000000000..3f68dfc11
--- /dev/null
+++ b/apps/edr-passenger-web/portal/src/features/support/AttachmentDraftBar.tsx
@@ -0,0 +1,59 @@
+'use client';
+
+import { FileText, X } from 'lucide-react';
+
+import { formatBytes } from './MessageAttachments';
+import type { PendingAttachment } from './useAttachmentDraft';
+
+/**
+ * The staged-files strip above the composer. Shows what will be sent and lets
+ * the visitor drop any of it before hitting send.
+ */
+export function AttachmentDraftBar({
+  attachments,
+  onRemove,
+}: {
+  attachments: PendingAttachment[];
+  onRemove: (id: string) => void;
+}) {
+  if (attachments.length === 0) return null;
+
+  return (
+    <div className="mb-2 flex flex-wrap gap-2">
+      {attachments.map((a) => (
+        <div
+          key={a.id}
+          className="relative flex items-center gap-1.5 rounded-lg border border-gray-200 p-1 pr-4 dark:border-slate-600"
+        >
+          {a.previewUrl ? (
+            // next/image can't take a `blob:` object URL — there's nothing at a
+            // routable origin for the optimizer to fetch.
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={a.previewUrl}
+              alt={a.file.name}
+              className="h-9 w-9 shrink-0 rounded object-cover"
+            />
+          ) : (
+            <span className="grid h-9 w-9 shrink-0 place-items-center rounded bg-gray-100 text-gray-500 dark:bg-slate-700 dark:text-slate-300">
+              <FileText size={16} />
+            </span>
+          )}
+          <span className="min-w-0 max-w-[120px]">
+            <span className="block truncate text-xs font-semibold text-gray-700 dark:text-slate-200">
+              {a.file.name}
+            </span>
+            <span className="block text-[10px] text-gray-400">{formatBytes(a.file.size)}</span>
+          </span>
+          <button
+            onClick={() => onRemove(a.id)}
+            aria-label={`Remove ${a.file.name}`}
+            className="absolute -right-1.5 -top-1.5 grid h-4 w-4 place-items-center rounded-full bg-gray-600 text-white transition hover:bg-gray-800"
+          >
+            <X size={10} />
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/edr-passenger-web/portal/src/features/support/ImagePreview.tsx b/apps/edr-passenger-web/portal/src/features/support/ImagePreview.tsx
new file mode 100644
index 000000000..8e6727291
--- /dev/null
+++ b/apps/edr-passenger-web/portal/src/features/support/ImagePreview.tsx
@@ -0,0 +1,73 @@
+'use client';
+
+import { X } from 'lucide-react';
+import { useEffect } from 'react';
+import { createPortal } from 'react-dom';
+
+/**
+ * Full-bleed preview for an image attachment.
+ *
+ * Deliberately local and hand-rolled rather than `@edr/ui-common`'s FileViewer:
+ * that component is Mantine-based and this app mounts no MantineProvider, so
+ * importing it would throw at runtime. All we need here is a backdrop and an
+ * `<img>`.
+ *
+ * Portalled to `document.body` because its call site is nested inside the chat
+ * panel, which is `overflow-hidden` and lives in the launcher's `z-30` stacking
+ * context. Rendered in place, the z-[120] below would be trapped in that context
+ * and mean nothing; portalled, it genuinely reaches the modal tier and paints
+ * over the chat that opened it.
+ *
+ * Only ever rendered for image mime types: `<img>` cannot execute its source,
+ * whereas navigating to or framing an attachment could. SVG is excluded from the
+ * allowed upload types upstream for exactly this reason.
+ */
+export function ImagePreview({
+  src,
+  alt,
+  onClose,
+}: {
+  src: string;
+  alt: string;
+  onClose: () => void;
+}) {
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [onClose]);
+
+  return createPortal(
+    <div
+      onClick={onClose}
+      role="dialog"
+      aria-modal="true"
+      aria-label={alt}
+      className="fixed inset-0 z-[120] flex items-center justify-center bg-black/80 p-6"
+    >
+      <button
+        onClick={onClose}
+        aria-label="Close preview"
+        className="absolute right-4 top-4 rounded-full bg-white/10 p-2 text-white transition hover:bg-white/20"
+      >
+        <X size={20} />
+      </button>
+      {/* Stop the backdrop's close handler firing when the image itself is
+          clicked — panning a zoomed screenshot shouldn't dismiss it. */}
+      {/* Plain <img>: `src` is a blob: object URL fetched through the
+          authenticated client, which next/image cannot optimize. */}
+      {/* eslint-disable-next-line @next/next/no-img-element */}
+      <img
+        src={src}
+        alt={alt}
+        onClick={(e) => e.stopPropagation()}
+        className="max-h-full max-w-full rounded-lg object-contain shadow-2xl"
+      />
+    </div>,
+    document.body,
+  );
+}
+
+export default ImagePreview;
diff --git a/apps/edr-passenger-web/portal/src/features/support/MessageAttachments.tsx b/apps/edr-passenger-web/portal/src/features/support/MessageAttachments.tsx
new file mode 100644
index 000000000..b446f2141
--- /dev/null
+++ b/apps/edr-passenger-web/portal/src/features/support/MessageAttachments.tsx
@@ -0,0 +1,108 @@
+'use client';
+
+import { isSupportAttachmentImage, type Passenger } from '@edr/types';
+import { FileText, ImageOff } from 'lucide-react';
+
+import { useAttachmentObjectUrl } from './useAttachmentObjectUrl';
+
+type AttachmentDto = Passenger.PassengerSupportAttachmentDto;
+
+/** Human-readable size — kept coarse; nobody needs bytes in a chat bubble. */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * One image attachment. Its own component because the bytes are fetched through
+ * the authenticated client (see {@link useAttachmentObjectUrl}) and a hook can't
+ * be called from inside a `.map()`.
+ */
+function ImageAttachment({
+  a,
+  onView,
+}: {
+  a: AttachmentDto;
+  onView: (a: AttachmentDto, src: string) => void;
+}) {
+  const { src, failed } = useAttachmentObjectUrl(a.url);
+
+  if (failed) {
+    return (
+      <span className="flex items-center gap-1.5 text-xs opacity-75">
+        <ImageOff size={14} className="shrink-0" />
+        Couldn&apos;t load {a.name}
+      </span>
+    );
+  }
+
+  if (!src) {
+    return (
+      <div className="h-[120px] w-[200px] animate-pulse rounded-lg bg-black/10 dark:bg-white/10" />
+    );
+  }
+
+  return (
+    <button
+      onClick={() => onView(a, src)}
+      className="block overflow-hidden rounded-lg"
+      aria-label={`View ${a.name}`}
+    >
+      {/* Capped: a tall screenshot would otherwise push the whole conversation
+          off-screen. Plain <img>: the source is a blob: object URL, which
+          next/image cannot optimize. */}
+      {/* eslint-disable-next-line @next/next/no-img-element */}
+      <img
+        src={src}
+        alt={a.name}
+        className="max-h-[220px] max-w-[240px] cursor-zoom-in rounded-lg object-cover"
+      />
+    </button>
+  );
+}
+
+/**
+ * Attachments inside a message bubble: images as thumbnails, everything else as
+ * a labelled file row. Non-images are not fetched until opened — pulling every
+ * document in a thread just to draw a filename would be wasteful.
+ */
+export function MessageAttachments({
+  attachments,
+  mine,
+  onViewImage,
+  onOpenFile,
+}: {
+  attachments: AttachmentDto[];
+  mine: boolean;
+  onViewImage: (a: AttachmentDto, src: string) => void;
+  onOpenFile: (a: AttachmentDto) => void;
+}) {
+  if (attachments.length === 0) return null;
+
+  return (
+    <div className="mt-1.5 space-y-1.5">
+      {attachments.map((a) =>
+        isSupportAttachmentImage(a.mimeType) ? (
+          <ImageAttachment key={a.id} a={a} onView={onViewImage} />
+        ) : (
+          <button
+            key={a.id}
+            onClick={() => onOpenFile(a)}
+            className={`flex w-full items-center gap-2 rounded-lg px-2 py-1.5 text-left transition ${
+              mine
+                ? 'bg-white/20 hover:bg-white/30'
+                : 'border border-gray-200 bg-white hover:bg-gray-50 dark:border-slate-600 dark:bg-slate-700 dark:hover:bg-slate-600'
+            }`}
+          >
+            <FileText size={16} className="shrink-0" />
+            <span className="min-w-0">
+              <span className="block truncate text-xs font-semibold">{a.name}</span>
+              <span className="block text-[10px] opacity-75">{formatBytes(a.size)}</span>
+            </span>
+          </button>
+        ),
+      )}
+    </div>
+  );
+}
diff --git a/apps/edr-passenger-web/portal/src/features/support/SupportPanel.tsx b/apps/edr-passenger-web/portal/src/features/support/SupportPanel.tsx
index 24b6b82fd..520573426 100644
--- a/apps/edr-passenger-web/portal/src/features/support/SupportPanel.tsx
+++ b/apps/edr-passenger-web/portal/src/features/support/SupportPanel.tsx
@@ -1,13 +1,22 @@
 'use client';
 
-import { Passenger } from '@edr/types';
-import { Headset, Send, X } from 'lucide-react';
-import { useEffect, useRef, useState } from 'react';
+import { Passenger, SUPPORT_ATTACHMENT_ACCEPT } from '@edr/types';
+import { Headset, Paperclip, Send, X } from 'lucide-react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 
+import { AttachmentDraftBar } from './AttachmentDraftBar';
+import { ImagePreview } from './ImagePreview';
+import { MessageAttachments } from './MessageAttachments';
+import { useAttachmentDraft } from './useAttachmentDraft';
+import { useLazyAttachmentObjectUrl } from './useAttachmentObjectUrl';
 import { useMarkRead, useSendMessage, useThread } from './useSupport';
 
 const GREEN = 'rgb(20 113 76)';
 type MessageDto = Passenger.PassengerSupportMessageDto;
+type AttachmentDto = Passenger.PassengerSupportAttachmentDto;
+
+/** How close to an edge counts as "at" it, in px. */
+const SCROLL_EDGE_SLOP = 40;
 
 function formatTime(iso?: string | null): string {
   if (!iso) return '';
@@ -19,29 +28,122 @@ function formatTime(iso?: string | null): string {
 }
 
 export function SupportPanel({ onClose }: { onClose: () => void }) {
-  const { data, isLoading } = useThread();
+  const { messages, pageCount, isLoading, hasNextPage, isFetchingNextPage, fetchNextPage } =
+    useThread();
   const send = useSendMessage();
   const markRead = useMarkRead();
   const [draft, setDraft] = useState('');
+  const [dragging, setDragging] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // Holds the blob object URL the thumbnail already fetched, not the attachment
+  // itself — the preview can't load from `a.url` on its own (see MessageAttachments).
+  const [preview, setPreview] = useState<{ name: string; src: string } | null>(null);
   const viewport = useRef<HTMLDivElement>(null);
+  const fileInput = useRef<HTMLInputElement>(null);
+  const attach = useAttachmentDraft(setError);
+  const loadAttachment = useLazyAttachmentObjectUrl();
 
-  const messages = data?.messages ?? [];
+  /**
+   * Scroll height captured just before an older page was requested, tagged with
+   * the page count at that moment.
+   *
+   * The page count is what makes this safe. Keyed on presence alone, a message
+   * arriving over the socket while history was still in flight would consume the
+   * snapshot on a one-bubble append, and the real 30-message prepend would then
+   * land with nothing to correct against — throwing the visitor exactly as far as
+   * this exists to prevent. Comparing counts means only an actual new page can
+   * claim it.
+   */
+  const pendingRestore = useRef<{ height: number; atPageCount: number } | null>(null);
+  /** Whether the visitor is parked at the bottom and wants to follow new messages. */
+  const stick = useRef(true);
+
+  const messageCount = messages.length;
 
   // Mark read on open + whenever new messages arrive.
   useEffect(() => {
     markRead.mutate();
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [messages.length]);
+  }, [messageCount]);
 
-  useEffect(() => {
-    viewport.current?.scrollTo({ top: viewport.current.scrollHeight });
-  }, [messages.length]);
+  /**
+   * Keep the viewport sensible as the list changes underneath it.
+   *
+   * Two different things change `messages`, and they want opposite behaviour: a
+   * new message at the bottom should follow (if the visitor is already there),
+   * while an older page prepended at the top must NOT move the content they're
+   * reading. Layout effect, not effect — this has to run before paint or the
+   * prepend visibly jumps.
+   */
+  useLayoutEffect(() => {
+    const el = viewport.current;
+    if (!el) return;
+    const restore = pendingRestore.current;
+    if (restore && pageCount > restore.atPageCount) {
+      // An older page went in above: push the scroll down by exactly the height
+      // that was added, so the same message stays under the cursor.
+      el.scrollTop += el.scrollHeight - restore.height;
+      pendingRestore.current = null;
+      return;
+    }
+    if (stick.current) el.scrollTo({ top: el.scrollHeight });
+  }, [messages, pageCount]);
+
+  const onScroll = () => {
+    const el = viewport.current;
+    if (!el) return;
+    const y = el.scrollTop;
+    stick.current = el.scrollHeight - y - el.clientHeight < SCROLL_EDGE_SLOP;
+    if (y < SCROLL_EDGE_SLOP && hasNextPage && !isFetchingNextPage) {
+      // A failed fetch leaves this set, which is harmless: the list didn't
+      // change, so the height is still accurate for the retry, and the count
+      // tag stops it being mistaken for a landed page in the meantime.
+      pendingRestore.current = {
+        height: el.scrollHeight,
+        atPageCount: pageCount,
+      };
+      fetchNextPage();
+    }
+  };
+
+  // Images already hold their bytes as an object URL from rendering the
+  // thumbnail, so reuse it rather than fetching the same file twice.
+  const viewImage = (a: AttachmentDto, src: string) => setPreview({ name: a.name, src });
+
+  /**
+   * Documents aren't fetched until opened. There's no inline viewer in this
+   * widget, so the bytes are handed to the browser as a download: a
+   * `window.open` after the await has lost its user-gesture and gets caught by
+   * popup blockers, whereas a synthetic anchor click does not.
+   */
+  const openFile = async (a: AttachmentDto) => {
+    try {
+      const src = await loadAttachment(a.url);
+      const link = document.createElement('a');
+      link.href = src;
+      link.download = a.name;
+      link.click();
+    } catch {
+      setError(`Couldn't open ${a.name}.`);
+    }
+  };
 
   const submit = async () => {
     const text = draft.trim();
-    if (!text) return;
+    if (!text && attach.attachments.length === 0) return;
+    const files = attach.files;
+    // Clear optimistically so the composer feels instant; on failure the text is
+    // restored below rather than silently lost.
     setDraft('');
-    await send.mutateAsync(text);
+    attach.clear();
+    setError(null);
+    stick.current = true;
+    try {
+      await send.mutateAsync({ text: text || undefined, attachments: files });
+    } catch (e) {
+      setDraft(text);
+      setError(e instanceof Error ? e.message : "Couldn't send that message.");
+    }
   };
 
   return (
@@ -49,7 +151,9 @@ export function SupportPanel({ onClose }: { onClose: () => void }) {
       {/* Header */}
       <div
         className="flex items-center justify-between gap-2 px-4 py-3 text-white"
-        style={{ background: `linear-gradient(135deg, ${GREEN}, rgb(30 140 96))` }}
+        style={{
+          background: `linear-gradient(135deg, ${GREEN}, rgb(30 140 96))`,
+        }}
       >
         <div className="flex items-center gap-2">
           <span className="flex h-8 w-8 items-center justify-center rounded-full bg-white/20">
@@ -60,17 +164,13 @@ export function SupportPanel({ onClose }: { onClose: () => void }) {
             <p className="text-xs text-white/80">We usually reply in a few minutes</p>
           </div>
         </div>
-        <button
-          onClick={onClose}
-          className="rounded-full p-1 hover:bg-white/20"
-          aria-label="Close"
-        >
+        <button onClick={onClose} className="rounded-full p-1 hover:bg-white/20" aria-label="Close">
           <X size={20} />
         </button>
       </div>
 
       {/* Messages */}
-      <div ref={viewport} className="flex-1 space-y-3 overflow-y-auto p-4">
+      <div ref={viewport} onScroll={onScroll} className="flex-1 space-y-3 overflow-y-auto p-4">
         {isLoading ? (
           <div className="p-8 text-center text-sm text-gray-400">Loading…</div>
         ) : messages.length === 0 ? (
@@ -81,20 +181,76 @@ export function SupportPanel({ onClose }: { onClose: () => void }) {
             >
               <Headset size={24} />
             </span>
-            Hi! 👋 How can we help you today? Send us a message and our team will
-            get back to you.
+            Hi! 👋 How can we help you today? Send us a message and our team will get back to you.
           </div>
         ) : (
-          messages.map((m) => <MessageBubble key={m.id} m={m} />)
+          <>
+            {isFetchingNextPage && (
+              <p className="py-1 text-center text-xs text-gray-400">Loading earlier messages…</p>
+            )}
+            {!hasNextPage && (
+              <p className="text-center text-[10px] text-gray-400">Start of conversation</p>
+            )}
+            {messages.map((m) => (
+              <MessageBubble key={m.id} m={m} onViewImage={viewImage} onOpenFile={openFile} />
+            ))}
+          </>
         )}
       </div>
 
       {/* Composer */}
-      <div className="border-t border-gray-100 p-3 dark:border-slate-700">
+      <div
+        className={`border-t p-3 ${
+          dragging
+            ? 'border-emerald-500 bg-emerald-50 dark:bg-emerald-950/30'
+            : 'border-gray-100 dark:border-slate-700'
+        }`}
+        onDragOver={(e) => {
+          e.preventDefault();
+          setDragging(true);
+        }}
+        onDragLeave={() => setDragging(false)}
+        onDrop={(e) => {
+          e.preventDefault();
+          setDragging(false);
+          attach.add(Array.from(e.dataTransfer.files));
+        }}
+      >
+        {error && (
+          <p className="mb-2 text-xs text-red-600 dark:text-red-400" role="alert">
+            {error}
+          </p>
+        )}
+        <AttachmentDraftBar attachments={attach.attachments} onRemove={attach.remove} />
         <div className="flex items-end gap-2">
+          <input
+            ref={fileInput}
+            type="file"
+            multiple
+            accept={SUPPORT_ATTACHMENT_ACCEPT}
+            hidden
+            onChange={(e) => {
+              attach.add(Array.from(e.currentTarget.files ?? []));
+              // Reset so picking the same file twice in a row still fires change.
+              e.currentTarget.value = '';
+            }}
+          />
+          <button
+            onClick={() => fileInput.current?.click()}
+            aria-label="Attach files"
+            className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg text-gray-500 transition hover:bg-gray-100 dark:text-slate-400 dark:hover:bg-slate-800"
+          >
+            <Paperclip size={18} />
+          </button>
           <textarea
             value={draft}
             onChange={(e) => setDraft(e.target.value)}
+            // Screenshots land on the clipboard as files. Take them and suppress
+            // the default, which would otherwise also paste the image's name (or
+            // nothing) as text.
+            onPaste={(e) => {
+              if (attach.addFromPaste(e.clipboardData)) e.preventDefault();
+            }}
             onKeyDown={(e) => {
               if (e.key === 'Enter' && !e.shiftKey) {
                 e.preventDefault();
@@ -102,12 +258,12 @@ export function SupportPanel({ onClose }: { onClose: () => void }) {
               }
             }}
             rows={1}
-            placeholder="Type a message…"
+            placeholder="Type a message, or paste an image…"
             className="max-h-24 flex-1 resize-none rounded-lg border border-gray-300 px-3 py-2 text-sm outline-none focus:border-emerald-500 dark:border-slate-600 dark:bg-slate-800 dark:text-white"
           />
           <button
             onClick={submit}
-            disabled={!draft.trim() || send.isPending}
+            disabled={(!draft.trim() && attach.attachments.length === 0) || send.isPending}
             className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg text-white transition hover:opacity-90 disabled:opacity-50"
             style={{ background: GREEN }}
             aria-label="Send"
@@ -116,19 +272,29 @@ export function SupportPanel({ onClose }: { onClose: () => void }) {
           </button>
         </div>
       </div>
+
+      {preview && (
+        <ImagePreview src={preview.src} alt={preview.name} onClose={() => setPreview(null)} />
+      )}
     </div>
   );
 }
 
-function MessageBubble({ m }: { m: MessageDto }) {
+function MessageBubble({
+  m,
+  onViewImage,
+  onOpenFile,
+}: {
+  m: MessageDto;
+  onViewImage: (a: AttachmentDto, src: string) => void;
+  onOpenFile: (a: AttachmentDto) => void;
+}) {
   const mine = m.sender === 'USER';
   return (
     <div className={`flex ${mine ? 'justify-end' : 'justify-start'}`}>
       <div className="max-w-[78%]">
         {!mine && (
-          <p className="mb-0.5 ml-1 text-xs text-gray-400">
-            {m.authorName || 'Support agent'}
-          </p>
+          <p className="mb-0.5 ml-1 text-xs text-gray-400">{m.authorName || 'Support agent'}</p>
         )}
         <div
           className={`whitespace-pre-wrap break-words rounded-2xl px-3 py-2 text-sm ${
@@ -138,13 +304,17 @@ function MessageBubble({ m }: { m: MessageDto }) {
           }`}
           style={mine ? { background: GREEN } : undefined}
         >
-          {m.text}
+          {/* Attachment-only messages carry text: "" — rendering it anyway would
+              leave an empty line above the thumbnail. */}
+          {m.text && <p>{m.text}</p>}
+          <MessageAttachments
+            attachments={m.attachments}
+            mine={mine}
+            onViewImage={onViewImage}
+            onOpenFile={onOpenFile}
+          />
         </div>
-        <p
-          className={`mt-0.5 text-[10px] text-gray-400 ${
-            mine ? 'text-right' : 'text-left'
-          }`}
-        >
+        <p className={`mt-0.5 text-[10px] text-gray-400 ${mine ? 'text-right' : 'text-left'}`}>
           {formatTime(m.createdAt)}
         </p>
       </div>
diff --git a/apps/edr-passenger-web/portal/src/features/support/SupportWidget.tsx b/apps/edr-passenger-web/portal/src/features/support/SupportWidget.tsx
index 8a4100de9..aa3ccfc26 100644
--- a/apps/edr-passenger-web/portal/src/features/support/SupportWidget.tsx
+++ b/apps/edr-passenger-web/portal/src/features/support/SupportWidget.tsx
@@ -1,13 +1,13 @@
-'use client';
+"use client";
 
-import { Headset } from 'lucide-react';
-import { useState } from 'react';
+import { Headset } from "lucide-react";
+import { useState } from "react";
 
-import { SupportPanel } from './SupportPanel';
-import { useUnreadCount } from './useSupport';
-import { useSupportSocket } from './useSupportSocket';
+import { SupportPanel } from "./SupportPanel";
+import { useUnreadCount } from "./useSupport";
+import { useSupportSocket } from "./useSupportSocket";
 
-const GREEN = 'rgb(20 113 76)';
+const GREEN = "rgb(20 113 76)";
 const GRADIENT = `linear-gradient(135deg, ${GREEN}, rgb(30 140 96))`;
 
 /**
@@ -27,14 +27,17 @@ export function SupportWidget() {
     // bottom action bars (z-40) used on booking flow pages, so the floating launcher never
     // paints over dialog content or a page's "Continue" bar — it only sits above ordinary
     // in-page content.
-    <div className="fixed bottom-6 right-6 z-30 flex flex-col items-end gap-3">
+    <div className="fixed bottom-6 right-6 z-40 flex flex-col items-end gap-3">
       {open && <SupportPanel onClose={() => setOpen(false)} />}
       {!open && (
         <button
           onClick={() => setOpen(true)}
           aria-label="Open support chat"
           className="group relative flex items-center gap-2.5 rounded-full p-2 pr-2 text-white transition-transform duration-150 hover:-translate-y-0.5 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-[3px] focus-visible:outline-primary active:translate-y-0 motion-reduce:transition-none motion-reduce:hover:translate-y-0 sm:pr-5"
-          style={{ background: GRADIENT, boxShadow: '0 10px 28px rgba(20,113,76,0.4)' }}
+          style={{
+            background: GRADIENT,
+            boxShadow: "0 10px 28px rgba(20,113,76,0.4)",
+          }}
         >
           {/* Faint breathing ring; the unread badge is loud enough on its own. */}
           {unread === 0 && (
@@ -56,7 +59,7 @@ export function SupportWidget() {
 
           {unread > 0 && (
             <span className="absolute -right-1 -top-1 flex h-5 min-w-5 items-center justify-center rounded-full border-2 border-white bg-red-500 px-1 text-xs font-bold text-white">
-              {unread > 9 ? '9+' : unread}
+              {unread > 9 ? "9+" : unread}
             </span>
           )}
         </button>
diff --git a/apps/edr-passenger-web/portal/src/features/support/supportApi.ts b/apps/edr-passenger-web/portal/src/features/support/supportApi.ts
index c33eef760..4d35118bc 100644
--- a/apps/edr-passenger-web/portal/src/features/support/supportApi.ts
+++ b/apps/edr-passenger-web/portal/src/features/support/supportApi.ts
@@ -6,20 +6,81 @@ import { getDeviceId } from './deviceIdentity';
 type ThreadDto = Passenger.PassengerSupportThreadDto;
 type MessageDto = Passenger.PassengerSupportMessageDto;
 
+/** Messages per page when walking the thread backwards. */
+export const MESSAGES_PAGE_SIZE = 30;
+
+export interface GetThreadParams {
+  /** Opaque cursor from the previous page's `nextCursor`; omit for the newest page. */
+  before?: string;
+  limit?: number;
+}
+
+/** What the composer hands over: text, files, or both (never neither). */
+export interface SendMessageInput {
+  text?: string;
+  attachments?: File[];
+}
+
+/**
+ * A message with files goes as multipart so the server persists them against the
+ * message it creates in the same request; text-only stays JSON.
+ *
+ * The `Content-Type: undefined` override is load-bearing, not cargo cult.
+ * `apiClient` pins `application/json` as an instance default, and axios's
+ * request transform reads that header to decide what to do with a FormData body:
+ * when it sees JSON it runs the form through `formDataToJSON` and posts *that*,
+ * so the files would be silently dropped and the server would see an empty
+ * message. Clearing the header lets axios's XHR adapter set `multipart/form-data`
+ * itself, with the boundary — which is also why we never write that value by
+ * hand: a hand-set Content-Type has no boundary and fails to parse.
+ */
+function toRequestBody(input: SendMessageInput): {
+  data: FormData | { deviceId: string; text?: string };
+  config?: { headers: Record<string, undefined> };
+} {
+  const deviceId = getDeviceId();
+  if (!input.attachments?.length) {
+    return { data: { deviceId, text: input.text } };
+  }
+
+  const form = new FormData();
+  form.append('deviceId', deviceId);
+  // Attachment-only messages send an empty string rather than omitting the
+  // field — the DTO models text as "" for those, not as absent.
+  form.append('text', input.text ?? '');
+  for (const file of input.attachments) form.append('attachments', file);
+  return { data: form, config: { headers: { 'Content-Type': undefined } } };
+}
+
 /**
  * Passenger portal support-chat calls — a single device-scoped thread. No auth,
  * no forms; everything is keyed by a localStorage device id.
  */
 export const supportApi = {
-  getThread: (): Promise<ThreadDto> =>
+  /**
+   * The device's thread. Returns the *newest page* of messages plus a cursor —
+   * not the whole conversation; page backwards with `before`.
+   */
+  getThread: (params: GetThreadParams = {}): Promise<ThreadDto> =>
     apiClient.get('/support/device/thread', {
-      params: { deviceId: getDeviceId() },
-    }),
-  sendMessage: (text: string): Promise<MessageDto> =>
-    apiClient.post('/support/device/messages', {
-      deviceId: getDeviceId(),
-      text,
+      params: { deviceId: getDeviceId(), ...params },
     }),
+  sendMessage: (input: SendMessageInput): Promise<MessageDto> => {
+    const { data, config } = toRequestBody(input);
+    return apiClient.post('/support/device/messages', data, config);
+  },
+  /**
+   * Attachment bytes, fetched through this client rather than linked directly:
+   * the API guard reads the bearer token from the `Authorization` header with no
+   * cookie fallback, and an `<img src>` can't carry that header — it would 401.
+   *
+   * `relativeUrl` is the DTO's `url` (`/support/attachments/:id`); the passenger
+   * API has no global prefix, so it appends to the client's baseURL as-is.
+   * `apiClient.get` unwraps a `{ data }` envelope when it finds one; a Blob has
+   * no such property, so the body comes back untouched.
+   */
+  fetchAttachment: (relativeUrl: string): Promise<Blob> =>
+    apiClient.get<Blob>(relativeUrl, { responseType: 'blob' }),
   markRead: (): Promise<{ unreadCount: number }> =>
     apiClient.post('/support/device/read', { deviceId: getDeviceId() }),
   unreadCount: (): Promise<{ unreadCount: number }> =>
diff --git a/apps/edr-passenger-web/portal/src/features/support/useAttachmentDraft.ts b/apps/edr-passenger-web/portal/src/features/support/useAttachmentDraft.ts
new file mode 100644
index 000000000..feb6b8d74
--- /dev/null
+++ b/apps/edr-passenger-web/portal/src/features/support/useAttachmentDraft.ts
@@ -0,0 +1,123 @@
+'use client';
+
+import {
+  isSupportAttachmentAllowed,
+  isSupportAttachmentImage,
+  SUPPORT_ATTACHMENT_MAX_BYTES,
+  SUPPORT_ATTACHMENT_MAX_PER_MESSAGE,
+} from '@edr/types';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/** A file staged in the composer, not yet sent. */
+export interface PendingAttachment {
+  /** Local-only id; the server id doesn't exist until the message is sent. */
+  id: string;
+  file: File;
+  /** Object URL, images only. Revoked when the entry goes away. */
+  previewUrl?: string;
+}
+
+let nextId = 0;
+
+/**
+ * Staging area for files being attached to a message.
+ *
+ * Files are held client-side until send, then posted alongside the text in one
+ * multipart request — there's no upload-then-reference step, so nothing to
+ * garbage-collect if the visitor changes their mind.
+ *
+ * Object URLs for image previews are revoked on removal and unmount; without
+ * that, pasting screenshots into a long-lived page leaks the full bytes of every
+ * image for the life of the tab.
+ */
+export function useAttachmentDraft(onReject?: (reason: string) => void) {
+  const [attachments, setAttachments] = useState<PendingAttachment[]>([]);
+  const rejectRef = useRef(onReject);
+  rejectRef.current = onReject;
+
+  // Read from a ref in the unmount cleanup so it doesn't re-run (and revoke
+  // still-live URLs) on every change to the list.
+  const attachmentsRef = useRef(attachments);
+  attachmentsRef.current = attachments;
+  useEffect(
+    () => () => {
+      for (const a of attachmentsRef.current) {
+        if (a.previewUrl) URL.revokeObjectURL(a.previewUrl);
+      }
+    },
+    [],
+  );
+
+  const add = useCallback((files: File[]) => {
+    if (files.length === 0) return;
+    setAttachments((current) => {
+      const accepted: PendingAttachment[] = [];
+      for (const file of files) {
+        if (current.length + accepted.length >= SUPPORT_ATTACHMENT_MAX_PER_MESSAGE) {
+          rejectRef.current?.(`Up to ${SUPPORT_ATTACHMENT_MAX_PER_MESSAGE} files per message.`);
+          break;
+        }
+        if (!isSupportAttachmentAllowed(file.type)) {
+          rejectRef.current?.(`${file.name}: that file type isn't supported.`);
+          continue;
+        }
+        if (file.size > SUPPORT_ATTACHMENT_MAX_BYTES) {
+          rejectRef.current?.(
+            `${file.name} is over the ${SUPPORT_ATTACHMENT_MAX_BYTES / (1024 * 1024)}MB limit.`,
+          );
+          continue;
+        }
+        accepted.push({
+          id: `pending-${nextId++}`,
+          file,
+          previewUrl: isSupportAttachmentImage(file.type) ? URL.createObjectURL(file) : undefined,
+        });
+      }
+      return accepted.length ? [...current, ...accepted] : current;
+    });
+  }, []);
+
+  const remove = useCallback((id: string) => {
+    setAttachments((current) => {
+      const target = current.find((a) => a.id === id);
+      if (target?.previewUrl) URL.revokeObjectURL(target.previewUrl);
+      return current.filter((a) => a.id !== id);
+    });
+  }, []);
+
+  const clear = useCallback(() => {
+    setAttachments((current) => {
+      for (const a of current) {
+        if (a.previewUrl) URL.revokeObjectURL(a.previewUrl);
+      }
+      return [];
+    });
+  }, []);
+
+  /**
+   * Pull files off a paste. Returns true if anything was taken, so the caller
+   * can suppress the default paste — otherwise pasting a screenshot also drops
+   * its filename (or nothing) into the textarea.
+   *
+   * Copying an image in most apps puts BOTH the bitmap and some text/html on the
+   * clipboard, so check for files first and only then let the text through.
+   */
+  const addFromPaste = useCallback(
+    (clipboard: DataTransfer | null): boolean => {
+      const files = Array.from(clipboard?.files ?? []);
+      if (files.length === 0) return false;
+      add(files);
+      return true;
+    },
+    [add],
+  );
+
+  return {
+    attachments,
+    files: attachments.map((a) => a.file),
+    add,
+    addFromPaste,
+    remove,
+    clear,
+  };
+}
diff --git a/apps/edr-passenger-web/portal/src/features/support/useAttachmentObjectUrl.ts b/apps/edr-passenger-web/portal/src/features/support/useAttachmentObjectUrl.ts
new file mode 100644
index 000000000..15a80c999
--- /dev/null
+++ b/apps/edr-passenger-web/portal/src/features/support/useAttachmentObjectUrl.ts
@@ -0,0 +1,79 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { supportApi } from './supportApi';
+
+/**
+ * Blob object URL for an attachment, or `undefined` while it loads / on failure.
+ *
+ * Chat attachments cannot be rendered with a direct `<img src={a.url}>`. The API
+ * guard takes the bearer token from the `Authorization` header and has no cookie
+ * fallback, and an `<img>` request cannot carry that header — a direct src is an
+ * unavoidable 401. So the bytes are fetched through the authenticated client and
+ * handed to the browser as an object URL.
+ *
+ * The URL is revoked on unmount and whenever the attachment changes, so a thread
+ * scrolled through hundreds of images doesn't pin all of them in memory.
+ */
+export function useAttachmentObjectUrl(relativeUrl: string): {
+  src?: string;
+  failed: boolean;
+} {
+  const [src, setSrc] = useState<string>();
+  const [failed, setFailed] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    let created: string | undefined;
+
+    setSrc(undefined);
+    setFailed(false);
+
+    supportApi
+      .fetchAttachment(relativeUrl)
+      .then((blob) => {
+        // The component may have unmounted mid-flight; creating a URL then would
+        // leak it, since the cleanup below has already run.
+        if (cancelled) return;
+        created = URL.createObjectURL(blob);
+        setSrc(created);
+      })
+      .catch(() => {
+        if (!cancelled) setFailed(true);
+      });
+
+    return () => {
+      cancelled = true;
+      if (created) URL.revokeObjectURL(created);
+    };
+  }, [relativeUrl]);
+
+  return { src, failed };
+}
+
+/**
+ * On-demand variant for files that aren't previewed inline (documents): fetch
+ * only when the user actually opens one, rather than pulling every attachment in
+ * the thread down just to render a filename row.
+ *
+ * Holds a single slot — opening another file revokes the previous URL, as does
+ * unmounting.
+ */
+export function useLazyAttachmentObjectUrl(): (relativeUrl: string) => Promise<string> {
+  const current = useRef<string>();
+
+  useEffect(
+    () => () => {
+      if (current.current) URL.revokeObjectURL(current.current);
+    },
+    [],
+  );
+
+  return useCallback(async (relativeUrl: string) => {
+    const blob = await supportApi.fetchAttachment(relativeUrl);
+    if (current.current) URL.revokeObjectURL(current.current);
+    current.current = URL.createObjectURL(blob);
+    return current.current;
+  }, []);
+}
diff --git a/apps/edr-passenger-web/portal/src/features/support/useSupport.ts b/apps/edr-passenger-web/portal/src/features/support/useSupport.ts
index 14b8518c8..5f00f8d93 100644
--- a/apps/edr-passenger-web/portal/src/features/support/useSupport.ts
+++ b/apps/edr-passenger-web/portal/src/features/support/useSupport.ts
@@ -1,19 +1,132 @@
 'use client';
 
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import type { Passenger } from '@edr/types';
+import {
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type InfiniteData,
+  type QueryClient,
+  type UseInfiniteQueryResult,
+} from '@tanstack/react-query';
+import { useMemo } from 'react';
 
-import { supportApi } from './supportApi';
+import { MESSAGES_PAGE_SIZE, supportApi, type SendMessageInput } from './supportApi';
+
+type ThreadDto = Passenger.PassengerSupportThreadDto;
+type MessageDto = Passenger.PassengerSupportMessageDto;
+type ConversationDto = Passenger.PassengerSupportConversationDto;
 
 export const SUPPORT_THREAD_KEY = ['support', 'thread'];
 export const SUPPORT_UNREAD_KEY = ['support', 'unread'];
 
-/** The device's single support thread (conversation + messages). */
-export function useThread(enabled = true) {
-  return useQuery({
+/**
+ * The device's single support thread, paged backwards from newest.
+ *
+ * react-query's "next page" is *older* history here, so `pages` runs
+ * newest-block-first and has to be reversed to render top-to-bottom in time
+ * order. Cursor-based rather than offset so a message arriving mid-scroll can't
+ * shift or duplicate the pages already loaded.
+ */
+// The return type is spelled out rather than inferred: spreading the query
+// result produces an anonymous type that names symbols from `query-core`, which
+// pnpm's non-flat node_modules makes unnameable from here (TS2742).
+export function useThread(enabled = true): UseInfiniteQueryResult<
+  InfiniteData<ThreadDto>,
+  Error
+> & {
+  conversation: ConversationDto | null;
+  messages: MessageDto[];
+  pageCount: number;
+} {
+  const query = useInfiniteQuery({
     queryKey: SUPPORT_THREAD_KEY,
-    queryFn: () => supportApi.getThread(),
+    queryFn: ({ pageParam }) =>
+      supportApi.getThread({ before: pageParam, limit: MESSAGES_PAGE_SIZE }),
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
     enabled,
   });
+
+  // Page 0 is the newest fetch, so its conversation carries the freshest status
+  // and unread count even after older pages load.
+  const conversation = query.data?.pages[0]?.conversation ?? null;
+
+  const messages = useMemo(
+    () => [...(query.data?.pages ?? [])].reverse().flatMap((p) => p.messages),
+    [query.data],
+  );
+
+  // `pageCount` is exposed so the view can tell a prepended history page from a
+  // message appended at the bottom — `messages` changing says nothing about which.
+  return {
+    ...query,
+    conversation,
+    messages,
+    pageCount: query.data?.pages.length ?? 0,
+  };
+}
+
+/**
+ * Splice a newly-arrived message into the cached thread.
+ *
+ * Deliberately not `invalidateQueries`: the thread is paginated, so refetching
+ * would re-request *every* page the visitor has scrolled back through on every
+ * single inbound message — the cost of a message would grow with how far they've
+ * read. Page 0 is the newest block and its messages are oldest-first within the
+ * block, so a new message belongs on its end.
+ *
+ * Doesn't seed the cache when the thread isn't loaded: a partial cache here would
+ * leave a thread whose "first page" is one message and whose `nextCursor` is
+ * missing — which would render as a complete conversation with no way to page
+ * back. The caller is told instead, via the outcome below.
+ */
+/**
+ * Why this reports an outcome rather than nothing: the two ways it can decline to
+ * append need opposite handling. A duplicate is our own echo and must be ignored —
+ * refetching there would undo the whole point. "Uncached" means the thread's first
+ * page is still in flight and may have been read on the server *before* this
+ * message existed, so dropping it silently would lose it until something else
+ * happened to refetch; the caller refetches instead. That's cheap precisely
+ * because nothing is loaded yet.
+ */
+export type AppendOutcome = 'appended' | 'duplicate' | 'uncached';
+
+export function appendMessageToCache(qc: QueryClient, message: MessageDto): AppendOutcome {
+  let outcome: AppendOutcome = 'uncached';
+  qc.setQueryData<InfiniteData<ThreadDto>>(SUPPORT_THREAD_KEY, (current) => {
+    if (!current?.pages.length) return current;
+    const [newest, ...rest] = current.pages;
+    // Our own message arrives twice — once as the POST response, once as the
+    // socket echo. Ignore the duplicate rather than render it twice.
+    if (newest.messages.some((m) => m.id === message.id)) {
+      outcome = 'duplicate';
+      return current;
+    }
+    outcome = 'appended';
+    return {
+      ...current,
+      pages: [{ ...newest, messages: [...newest.messages, message] }, ...rest],
+    };
+  });
+  return outcome;
+}
+
+/**
+ * Replace the cached conversation with a freshly-pushed copy.
+ *
+ * Page 0 is where `useThread` reads the conversation from, so patching it there
+ * is enough; `messages` and `nextCursor` are left exactly as they were, which is
+ * the point — this must not disturb the paged history. No-op when the thread
+ * isn't cached: the in-flight fetch will bring the current conversation anyway.
+ */
+export function patchConversationInCache(qc: QueryClient, conversation: ConversationDto): void {
+  qc.setQueryData<InfiniteData<ThreadDto>>(SUPPORT_THREAD_KEY, (current) => {
+    if (!current?.pages.length) return current;
+    const [newest, ...rest] = current.pages;
+    return { ...current, pages: [{ ...newest, conversation }, ...rest] };
+  });
 }
 
 export function useUnreadCount(enabled = true) {
@@ -28,9 +141,11 @@ export function useUnreadCount(enabled = true) {
 export function useSendMessage() {
   const qc = useQueryClient();
   return useMutation({
-    mutationFn: (text: string) => supportApi.sendMessage(text),
+    mutationFn: (input: SendMessageInput) => supportApi.sendMessage(input),
+    // The gateway echoes our own message back over the socket, which appends it
+    // to the cache — so don't invalidate the thread here, or every send would
+    // refetch every page the visitor has scrolled through.
     onSuccess: () => {
-      qc.invalidateQueries({ queryKey: SUPPORT_THREAD_KEY });
       qc.invalidateQueries({ queryKey: SUPPORT_UNREAD_KEY });
     },
   });
@@ -40,8 +155,9 @@ export function useMarkRead() {
   const qc = useQueryClient();
   return useMutation({
     mutationFn: () => supportApi.markRead(),
+    // Same reasoning as above: reading a thread changes only the badge, and the
+    // messages already on screen are the ones being marked.
     onSuccess: () => {
-      qc.invalidateQueries({ queryKey: SUPPORT_THREAD_KEY });
       qc.invalidateQueries({ queryKey: SUPPORT_UNREAD_KEY });
     },
   });
diff --git a/apps/edr-passenger-web/portal/src/features/support/useSupportSocket.ts b/apps/edr-passenger-web/portal/src/features/support/useSupportSocket.ts
index 1bd21b7b8..8fea63d76 100644
--- a/apps/edr-passenger-web/portal/src/features/support/useSupportSocket.ts
+++ b/apps/edr-passenger-web/portal/src/features/support/useSupportSocket.ts
@@ -6,11 +6,17 @@ import { useEffect } from 'react';
 import { io } from 'socket.io-client';
 
 import { getDeviceId } from './deviceIdentity';
-import { SUPPORT_THREAD_KEY, SUPPORT_UNREAD_KEY } from './useSupport';
+import {
+  appendMessageToCache,
+  patchConversationInCache,
+  SUPPORT_THREAD_KEY,
+  SUPPORT_UNREAD_KEY,
+} from './useSupport';
 
-const SOCKET_ORIGIN = String(
-  process.env.NEXT_PUBLIC_API_URL || 'http://localhost:4000',
-).replace(/\/api\/?$/, '');
+const SOCKET_ORIGIN = String(process.env.NEXT_PUBLIC_API_URL || 'http://localhost:4000').replace(
+  /\/api\/?$/,
+  '',
+);
 
 /**
  * Subscribes the device to live support pushes. The gateway joins a
@@ -22,23 +28,42 @@ export function useSupportSocket(enabled: boolean) {
 
   useEffect(() => {
     if (!enabled || typeof window === 'undefined') return;
-    const socket = io(
-      `${SOCKET_ORIGIN}/${Passenger.PASSENGER_SUPPORT_WS_NAMESPACE}`,
-      {
-        auth: { guestId: getDeviceId() },
-        // Prefer WebSocket, fall back to HTTP long-polling if the proxy blocks
-        // the upgrade (polling rides normal HTTPS, already CSP-allowed).
-        transports: ['websocket', 'polling'],
-        withCredentials: true,
+    const socket = io(`${SOCKET_ORIGIN}/${Passenger.PASSENGER_SUPPORT_WS_NAMESPACE}`, {
+      auth: { guestId: getDeviceId() },
+      // Prefer WebSocket, fall back to HTTP long-polling if the proxy blocks
+      // the upgrade (polling rides normal HTTPS, already CSP-allowed).
+      transports: ['websocket', 'polling'],
+      withCredentials: true,
+    });
+
+    socket.on(
+      Passenger.PASSENGER_SUPPORT_WS_EVENTS.MESSAGE_NEW,
+      (event: Passenger.PassengerSupportMessageEvent) => {
+        // Append rather than invalidate: the thread is paginated now, and
+        // invalidating would refetch every loaded page on every inbound message.
+        if (appendMessageToCache(qc, event.message) === 'uncached') {
+          // The thread's first page is still loading and may have been read on
+          // the server before this message existed — without this it would go
+          // missing until some unrelated refetch. Cheap: no pages loaded yet.
+          qc.invalidateQueries({ queryKey: SUPPORT_THREAD_KEY });
+        }
+        qc.invalidateQueries({ queryKey: SUPPORT_UNREAD_KEY });
       },
     );
 
-    const refresh = () => {
-      qc.invalidateQueries({ queryKey: SUPPORT_THREAD_KEY });
-      qc.invalidateQueries({ queryKey: SUPPORT_UNREAD_KEY });
-    };
-    socket.on(Passenger.PASSENGER_SUPPORT_WS_EVENTS.MESSAGE_NEW, refresh);
-    socket.on(Passenger.PASSENGER_SUPPORT_WS_EVENTS.CONVERSATION_UPDATED, refresh);
+    // Patch the conversation in place rather than invalidating the thread key —
+    // the same key the paginated history uses. The server emits this alongside
+    // MESSAGE_NEW for *every* message, so invalidating here would refetch every
+    // page the visitor has scrolled back through on each one, cancelling out the
+    // append above entirely. The payload is the updated conversation, so there's
+    // nothing to go back to the server for.
+    socket.on(
+      Passenger.PASSENGER_SUPPORT_WS_EVENTS.CONVERSATION_UPDATED,
+      (conversation: Passenger.PassengerSupportConversationDto) => {
+        patchConversationInCache(qc, conversation);
+        qc.invalidateQueries({ queryKey: SUPPORT_UNREAD_KEY });
+      },
+    );
 
     return () => {
       socket.off();

From 149548a9b131b3ca4849ded3077175b0ea6d9876 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 18 Jul 2026 09:44:44 +0000
Subject: [PATCH 08/15] chore: packages

---
 pnpm-lock.yaml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6ace365ff..f59a388ba 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -841,6 +841,9 @@ importers:
       jose:
         specifier: ^5.10.0
         version: 5.10.0
+      minio:
+        specifier: 7.1.3
+        version: 7.1.3
       pg:
         specifier: ^8.21.0
         version: 8.21.0
@@ -893,6 +896,9 @@ importers:
       '@types/luxon':
         specifier: ^3.7.1
         version: 3.7.1
+      '@types/multer':
+        specifier: ^2.1.0
+        version: 2.1.0
       '@types/node':
         specifier: ^20.10.6
         version: 20.19.42

From ccd9afacb1a7a4b6e8535e4896fa1c7f46907476 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 20 Jul 2026 06:19:12 +0000
Subject: [PATCH 09/15] feat: setup forget password to the backoffice

---
 apps/edr-freight-web/backoffice/src/App.tsx   |   2 +
 .../backoffice/src/auth/api.ts                |  38 ++-
 .../backoffice/src/auth/types.ts              |  27 ++
 .../src/components/auth/OtpChannelStep.tsx    | 179 ++++++++++
 .../src/components/auth/PasswordChecklist.tsx |  41 +++
 .../backoffice/src/hooks/useResendCooldown.ts |  24 ++
 .../src/pages/auth/ForgotPasswordPage.tsx     | 318 ++++++++++++++++++
 .../backoffice/src/pages/auth/LoginPage.tsx   |  42 ++-
 .../backoffice/src/utils/identifier.ts        |  22 ++
 .../backoffice/src/utils/passwordSchema.ts    |  38 +++
 10 files changed, 708 insertions(+), 23 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/auth/OtpChannelStep.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/auth/PasswordChecklist.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/hooks/useResendCooldown.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/auth/ForgotPasswordPage.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/utils/identifier.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/utils/passwordSchema.ts

diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index ce90554a6..813595690 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -46,6 +46,7 @@ import {
 import { useAuth } from "./auth/useAuth";
 import LoadingScreen from "./components/LoadingScreen";
 import LoginPage from "./pages/auth/LoginPage";
+import ForgotPasswordPage from "./pages/auth/ForgotPasswordPage";
 import BookingContractPage from "./pages/bookings/BookingContractPage";
 import BookingRequestDetailPage from "./pages/bookings/BookingRequestDetailPage";
 import BookingRequestsPage from "./pages/bookings/BookingRequestsPage";
@@ -696,6 +697,7 @@ const App = () => {
     return (
       <Routes>
         <Route path="/auth" element={<LoginPage />} />
+        <Route path="/forgot-password" element={<ForgotPasswordPage />} />
         {/* <Route path="/um/*" element={<UserManagementHostPage />} /> */}
         <Route path="um/set-password" element={<SetPassword />} />
         <Route path="/callback" element={<FaydaCallbackPage />} />
diff --git a/apps/edr-freight-web/backoffice/src/auth/api.ts b/apps/edr-freight-web/backoffice/src/auth/api.ts
index f72e72949..240c55001 100644
--- a/apps/edr-freight-web/backoffice/src/auth/api.ts
+++ b/apps/edr-freight-web/backoffice/src/auth/api.ts
@@ -1,5 +1,13 @@
 import { api } from "./http";
-import type { AuthTokens, AuthUser, LoginResponse } from "./types";
+import type {
+  AuthTokens,
+  AuthUser,
+  ForgotPasswordRequestPayload,
+  ForgotPasswordVerifyPayload,
+  LoginResponse,
+  ResetTicket,
+  SetPasswordPayload,
+} from "./types";
 
 export const loginRequest = async (payload: {
   email: string;
@@ -21,3 +29,31 @@ export const getMeRequest = async () => {
   const response = await api.get<AuthUser>("/me");
   return response.data;
 };
+
+// The three calls below drive the unauthenticated forgot-password flow.
+// Responses under /api/auth are *flattened* by the API's response
+// interceptor ({ success, ...payload }), so there is no `.data.data` here.
+
+export const requestPasswordResetRequest = async (
+  payload: ForgotPasswordRequestPayload,
+) => {
+  await api.post("/auth/forgot-password/request", payload);
+};
+
+export const verifyPasswordResetOtpRequest = async (
+  payload: ForgotPasswordVerifyPayload,
+) => {
+  const response = await api.post<ResetTicket>(
+    "/auth/forgot-password/verify",
+    payload,
+  );
+  return response.data;
+};
+
+/**
+ * Spend the reset ticket minted by {@link verifyPasswordResetOtpRequest}.
+ * Carries its own userId/verificationCode and never touches the session.
+ */
+export const resetPasswordRequest = async (payload: SetPasswordPayload) => {
+  await api.patch("/auth/set-password", payload);
+};
diff --git a/apps/edr-freight-web/backoffice/src/auth/types.ts b/apps/edr-freight-web/backoffice/src/auth/types.ts
index 6279c8491..1c79819d5 100644
--- a/apps/edr-freight-web/backoffice/src/auth/types.ts
+++ b/apps/edr-freight-web/backoffice/src/auth/types.ts
@@ -58,6 +58,33 @@ export interface LoginResponse extends Partial<AuthTokens> {
   mfaRequired?: boolean;
 }
 
+/** The channel a password-reset code is delivered over. */
+export type ResetChannel = "email" | "phone";
+
+export interface ForgotPasswordRequestPayload {
+  /** Email, username, or E.164 phone — whatever the user typed, normalised. */
+  identifier: string;
+  channel: ResetChannel;
+}
+
+export interface ForgotPasswordVerifyPayload extends ForgotPasswordRequestPayload {
+  otp: string;
+}
+
+/** Single-use ticket to spend on `PATCH /api/auth/set-password`. */
+export interface ResetTicket {
+  userId: string;
+  verificationCode: string;
+}
+
+export interface SetPasswordPayload {
+  newPassword: string;
+  confirmPassword: string;
+  userId: string;
+  email: string;
+  verificationCode: string;
+}
+
 // Additional types for Matrix form test
 export interface User {
   id: string;
diff --git a/apps/edr-freight-web/backoffice/src/components/auth/OtpChannelStep.tsx b/apps/edr-freight-web/backoffice/src/components/auth/OtpChannelStep.tsx
new file mode 100644
index 000000000..b61bb2eab
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/auth/OtpChannelStep.tsx
@@ -0,0 +1,179 @@
+import { Alert, Button, PinInput, SegmentedControl, Stack, Text } from "@mantine/core";
+import {
+  AlertCircle,
+  ArrowLeft,
+  Mail,
+  RotateCw,
+  ShieldCheck,
+  Smartphone,
+} from "lucide-react";
+
+import { maskEmail, maskPhone } from "@/utils/identifier";
+
+export type OtpChannel = "phone" | "email";
+
+export const OTP_LENGTH = 6;
+
+export interface OtpChannelSelectProps {
+  value: OtpChannel;
+  onChange: (channel: OtpChannel) => void;
+  disabled?: boolean;
+  label?: string;
+}
+
+/** Phone/email toggle deciding where the verification code is sent. */
+export function OtpChannelSelect({
+  value,
+  onChange,
+  disabled,
+  label = "Send verification code via",
+}: OtpChannelSelectProps) {
+  return (
+    <div className="space-y-1.5">
+      <Text size="sm" fw={500} c="edr-text">
+        {label}
+      </Text>
+      <SegmentedControl
+        fullWidth
+        disabled={disabled}
+        value={value}
+        onChange={(v) => onChange(v as OtpChannel)}
+        data={[
+          {
+            value: "phone",
+            label: (
+              <span className="flex items-center justify-center gap-1.5">
+                <Smartphone size={14} /> Phone
+              </span>
+            ),
+          },
+          {
+            value: "email",
+            label: (
+              <span className="flex items-center justify-center gap-1.5">
+                <Mail size={14} /> Email
+              </span>
+            ),
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+export interface OtpChannelStepProps {
+  channel: OtpChannel;
+  /** Raw email or phone the code went to; masked before display. */
+  target: string;
+  value: string;
+  onChange: (otp: string) => void;
+  onVerify: () => void;
+  onBack: () => void;
+  onResend: () => void;
+  /** Seconds until resend is allowed; 0 enables the button. */
+  resendIn: number;
+  sending: boolean;
+  verifying: boolean;
+  error: string | null;
+  title?: string;
+  description?: string;
+  submitLabel: string;
+}
+
+/**
+ * The "enter the code we sent you" stage. Shared by signup and the
+ * forgot-password flow — both send through the same `/api/otp/*` service.
+ */
+export default function OtpChannelStep({
+  channel,
+  target,
+  value,
+  onChange,
+  onVerify,
+  onBack,
+  onResend,
+  resendIn,
+  sending,
+  verifying,
+  error,
+  title,
+  description,
+  submitLabel,
+}: OtpChannelStepProps) {
+  const maskedTarget = channel === "email" ? maskEmail(target) : maskPhone(target);
+  const busy = sending || verifying;
+
+  return (
+    <Stack gap="md">
+      <div className="mb-1 flex justify-center">
+        <span className="flex h-12 w-12 items-center justify-center rounded-full bg-primary/10 text-primary">
+          <ShieldCheck size={22} />
+        </span>
+      </div>
+
+      <div className="space-y-1.5 text-center">
+        <h1 className="text-xl font-bold tracking-tight text-gray-900 sm:text-2xl">
+          {title ?? `Verify your ${channel === "email" ? "email" : "phone"}`}
+        </h1>
+        <p className="text-sm leading-relaxed text-gray-500">
+          We sent a {OTP_LENGTH}-digit code to{" "}
+          <span className="font-medium text-gray-700">{maskedTarget}</span>.{" "}
+          {description ?? "Enter it to continue."}
+        </p>
+      </div>
+
+      {error ? (
+        <Alert color="red" variant="light" icon={<AlertCircle size={18} />}>
+          {error}
+        </Alert>
+      ) : null}
+
+      <Stack gap={6} align="center">
+        <Text size="sm" fw={500} c="edr-text">
+          Verification code
+        </Text>
+        <PinInput
+          length={OTP_LENGTH}
+          type="number"
+          oneTimeCode
+          value={value}
+          placeholder="0"
+          disabled={verifying}
+          styles={{ input: { textAlign: "center" } }}
+          onChange={onChange}
+        />
+      </Stack>
+
+      <Button
+        color="edr-green"
+        fullWidth
+        loading={verifying}
+        disabled={verifying || value.trim().length !== OTP_LENGTH}
+        onClick={onVerify}
+      >
+        {submitLabel}
+      </Button>
+
+      <div className="flex items-center justify-between">
+        <Button
+          variant="subtle"
+          color="gray"
+          leftSection={<ArrowLeft size={14} />}
+          disabled={busy}
+          onClick={onBack}
+        >
+          Back
+        </Button>
+        <Button
+          variant="subtle"
+          color="edr-green"
+          leftSection={<RotateCw size={14} />}
+          disabled={resendIn > 0 || busy}
+          onClick={onResend}
+        >
+          {resendIn > 0 ? `Resend in ${resendIn}s` : "Resend code"}
+        </Button>
+      </div>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/auth/PasswordChecklist.tsx b/apps/edr-freight-web/backoffice/src/components/auth/PasswordChecklist.tsx
new file mode 100644
index 000000000..89cea7a0e
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/auth/PasswordChecklist.tsx
@@ -0,0 +1,41 @@
+import { Check, X } from "lucide-react";
+
+import { passwordRequirements } from "@/utils/passwordSchema";
+
+export interface PasswordChecklistProps {
+  /** The current password value; the checklist hides itself when empty. */
+  value: string;
+}
+
+/** Live pass/fail list of the password rules, shown under a password field. */
+export default function PasswordChecklist({ value }: PasswordChecklistProps) {
+  if (!value) return null;
+
+  return (
+    <div className="mt-2 space-y-1">
+      {passwordRequirements.map((req) => {
+        const met = req.test(value);
+        return (
+          <div key={req.label} className="flex items-center gap-2">
+            <span
+              className={`flex h-4 w-4 shrink-0 items-center justify-center rounded-full ${
+                met
+                  ? "bg-primary text-primary-foreground"
+                  : "bg-gray-200 text-gray-500"
+              }`}
+            >
+              {met ? (
+                <Check className="h-2.5 w-2.5" />
+              ) : (
+                <X className="h-2.5 w-2.5" />
+              )}
+            </span>
+            <span className={`text-xs ${met ? "text-primary" : "text-gray-500"}`}>
+              {req.label}
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/hooks/useResendCooldown.ts b/apps/edr-freight-web/backoffice/src/hooks/useResendCooldown.ts
new file mode 100644
index 000000000..deeca8125
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/hooks/useResendCooldown.ts
@@ -0,0 +1,24 @@
+import { useEffect, useState } from "react";
+
+/** Seconds a user must wait before another OTP can be requested. */
+const DEFAULT_COOLDOWN_SECONDS = 60;
+
+/**
+ * Countdown that gates the "Resend code" button. Ticks with setTimeout rather
+ * than wall-clock arithmetic, so it needs no Date.now().
+ */
+export function useResendCooldown(seconds: number = DEFAULT_COOLDOWN_SECONDS) {
+  const [secondsLeft, setSecondsLeft] = useState(0);
+
+  useEffect(() => {
+    if (secondsLeft <= 0) return;
+    const t = setTimeout(() => setSecondsLeft((s) => s - 1), 1000);
+    return () => clearTimeout(t);
+  }, [secondsLeft]);
+
+  return {
+    secondsLeft,
+    start: () => setSecondsLeft(seconds),
+    reset: () => setSecondsLeft(0),
+  };
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/auth/ForgotPasswordPage.tsx b/apps/edr-freight-web/backoffice/src/pages/auth/ForgotPasswordPage.tsx
new file mode 100644
index 000000000..7a21c0d8b
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/auth/ForgotPasswordPage.tsx
@@ -0,0 +1,318 @@
+import { type FormEvent, useState } from "react";
+import { Alert, Button, PasswordInput, Stack, TextInput } from "@mantine/core";
+import { AlertCircle, ArrowLeft, ArrowRight, KeyRound } from "lucide-react";
+import { Link, useNavigate } from "react-router-dom";
+
+import {
+  requestPasswordResetRequest,
+  resetPasswordRequest,
+  verifyPasswordResetOtpRequest,
+} from "@/auth/api";
+import type { ResetTicket } from "@/auth/types";
+import AuthShell from "@/components/auth/AuthShell";
+import OtpChannelStep, {
+  OTP_LENGTH,
+  OtpChannelSelect,
+  type OtpChannel,
+} from "@/components/auth/OtpChannelStep";
+import PasswordChecklist from "@/components/auth/PasswordChecklist";
+import { useResendCooldown } from "@/hooks/useResendCooldown";
+import { normaliseIdentifier } from "@/utils/identifier";
+import { meetsAllRequirements } from "@/utils/passwordSchema";
+import { extractApiError } from "@/utils/result";
+
+type Stage = "identify" | "otp" | "password";
+
+const ForgotPasswordPage = () => {
+  const navigate = useNavigate();
+
+  const [stage, setStage] = useState<Stage>("identify");
+  const [identifier, setIdentifier] = useState("");
+  const [channel, setChannel] = useState<OtpChannel>("phone");
+  const [otpCode, setOtpCode] = useState("");
+  // The reset ticket lives in memory only — persisting it would leave a
+  // password-change credential sitting in localStorage.
+  const [ticket, setTicket] = useState<ResetTicket | null>(null);
+  const [password, setPassword] = useState("");
+  const [confirmPassword, setConfirmPassword] = useState("");
+
+  const [sending, setSending] = useState(false);
+  const [verifying, setVerifying] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const resendCooldown = useResendCooldown();
+
+  /** The identifier as the API will see it — normalised once, reused everywhere. */
+  const normalised = normaliseIdentifier(identifier);
+
+  const sendCode = async () => {
+    await requestPasswordResetRequest({ identifier: normalised, channel });
+    setOtpCode("");
+    resendCooldown.start();
+  };
+
+  // Stage 1 — ask for a code. The API answers identically for unknown accounts,
+  // so we always advance; a non-existent identifier simply never receives a code.
+  const handleIdentify = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError(null);
+    setSending(true);
+    try {
+      await sendCode();
+      setStage("otp");
+    } catch (err) {
+      setError(extractApiError(err).message);
+    } finally {
+      setSending(false);
+    }
+  };
+
+  const handleResend = async () => {
+    setError(null);
+    setSending(true);
+    try {
+      await sendCode();
+    } catch (err) {
+      setError(extractApiError(err).message);
+    } finally {
+      setSending(false);
+    }
+  };
+
+  // Stage 2 — trade the code for a single-use ticket.
+  const handleVerify = async () => {
+    setError(null);
+    if (otpCode.trim().length !== OTP_LENGTH) {
+      setError(`Enter the ${OTP_LENGTH}-digit code we sent you.`);
+      return;
+    }
+    setVerifying(true);
+    try {
+      const result = await verifyPasswordResetOtpRequest({
+        identifier: normalised,
+        channel,
+        otp: otpCode.trim(),
+      });
+      setTicket(result);
+      setStage("password");
+    } catch (err) {
+      setError(extractApiError(err).message);
+    } finally {
+      setVerifying(false);
+    }
+  };
+
+  // Stage 3 — spend the ticket on IAM's set-password.
+  const handleReset = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError(null);
+
+    if (!ticket) {
+      setError("Your reset session expired. Start again.");
+      setStage("identify");
+      return;
+    }
+    if (password !== confirmPassword) {
+      setError("Passwords do not match.");
+      return;
+    }
+
+    setVerifying(true);
+    try {
+      await resetPasswordRequest({
+        userId: ticket.userId,
+        // The API matches this against email / username / phone, so the typed
+        // identifier works regardless of which one it is.
+        email: normalised,
+        verificationCode: ticket.verificationCode,
+        newPassword: password,
+        confirmPassword,
+      });
+      navigate("/auth", {
+        replace: true,
+        state: { passwordReset: true },
+      });
+    } catch (err) {
+      setError(extractApiError(err).message);
+    } finally {
+      setVerifying(false);
+    }
+  };
+
+  const identifierLabel =
+    channel === "email" ? "the email on your account" : "the phone on your account";
+
+  return (
+    <AuthShell
+      tagline="Recover your account"
+      taglineBody="Reset your EDR Freight backoffice password with a one-time code sent to your email or phone."
+    >
+      <div className="flex w-full flex-col">
+        {stage === "identify" ? (
+          <form onSubmit={handleIdentify} className="flex w-full flex-col">
+            <div className="mb-1 flex justify-center">
+              <span className="flex h-12 w-12 items-center justify-center rounded-full bg-primary/10 text-primary">
+                <KeyRound size={22} />
+              </span>
+            </div>
+
+            <div className="mb-4 mt-3 space-y-1.5 text-center sm:mb-5">
+              <h1 className="text-xl font-bold tracking-tight text-gray-900 sm:text-2xl">
+                Forgot your password?
+              </h1>
+              <p className="text-sm leading-relaxed text-gray-500">
+                Enter your email or phone number and we&apos;ll send you a code to
+                reset it.
+              </p>
+            </div>
+
+            <Stack gap="md">
+              <TextInput
+                label="Email or Phone"
+                placeholder="name@company.com or 09XXXXXXXX"
+                autoComplete="username"
+                required
+                disabled={sending}
+                value={identifier}
+                onChange={(event) => setIdentifier(event.target.value)}
+              />
+
+              <OtpChannelSelect
+                value={channel}
+                onChange={setChannel}
+                disabled={sending}
+                label="Send the code to"
+              />
+
+              <p className="text-xs text-gray-500">
+                The code goes to {identifierLabel}, which may differ from what you
+                typed above.
+              </p>
+
+              {error ? (
+                <Alert color="red" variant="light" icon={<AlertCircle size={18} />}>
+                  {error}
+                </Alert>
+              ) : null}
+
+              <Button
+                type="submit"
+                color="edr-green"
+                fullWidth
+                loading={sending}
+                disabled={!identifier.trim()}
+                rightSection={!sending ? <ArrowRight size={16} /> : undefined}
+              >
+                Send code
+              </Button>
+
+              <p className="text-center text-sm text-gray-500">
+                Remembered it?{" "}
+                <Link to="/auth" className="font-semibold text-primary hover:underline">
+                  Back to sign in
+                </Link>
+              </p>
+            </Stack>
+          </form>
+        ) : null}
+
+        {stage === "otp" ? (
+          <OtpChannelStep
+            channel={channel}
+            target={normalised}
+            value={otpCode}
+            onChange={setOtpCode}
+            onVerify={handleVerify}
+            onBack={() => {
+              setStage("identify");
+              setError(null);
+            }}
+            onResend={handleResend}
+            resendIn={resendCooldown.secondsLeft}
+            sending={sending}
+            verifying={verifying}
+            error={error}
+            title="Enter your reset code"
+            description="Enter it to choose a new password."
+            submitLabel="Verify code"
+          />
+        ) : null}
+
+        {stage === "password" ? (
+          <form onSubmit={handleReset} className="flex w-full flex-col">
+            <div className="mb-4 space-y-1.5 text-center sm:mb-5">
+              <h1 className="text-xl font-bold tracking-tight text-gray-900 sm:text-2xl">
+                Choose a new password
+              </h1>
+              <p className="text-sm leading-relaxed text-gray-500">
+                Pick something strong you haven&apos;t used before.
+              </p>
+            </div>
+
+            <Stack gap="md">
+              <div>
+                <PasswordInput
+                  label="New password"
+                  placeholder="Create a strong password"
+                  required
+                  disabled={verifying}
+                  value={password}
+                  onChange={(event) => setPassword(event.target.value)}
+                />
+                <PasswordChecklist value={password} />
+              </div>
+
+              <PasswordInput
+                label="Confirm new password"
+                placeholder="Re-enter your password"
+                required
+                disabled={verifying}
+                error={
+                  confirmPassword && confirmPassword !== password
+                    ? "Passwords do not match"
+                    : undefined
+                }
+                value={confirmPassword}
+                onChange={(event) => setConfirmPassword(event.target.value)}
+              />
+
+              {error ? (
+                <Alert color="red" variant="light" icon={<AlertCircle size={18} />}>
+                  {error}
+                </Alert>
+              ) : null}
+
+              <Button
+                type="submit"
+                color="edr-green"
+                fullWidth
+                loading={verifying}
+                disabled={
+                  verifying ||
+                  !meetsAllRequirements(password) ||
+                  password !== confirmPassword
+                }
+              >
+                Reset password
+              </Button>
+
+              <Button
+                variant="subtle"
+                color="gray"
+                leftSection={<ArrowLeft size={14} />}
+                disabled={verifying}
+                onClick={() => {
+                  setStage("otp");
+                  setError(null);
+                }}
+              >
+                Back
+              </Button>
+            </Stack>
+          </form>
+        ) : null}
+      </div>
+    </AuthShell>
+  );
+};
+
+export default ForgotPasswordPage;
diff --git a/apps/edr-freight-web/backoffice/src/pages/auth/LoginPage.tsx b/apps/edr-freight-web/backoffice/src/pages/auth/LoginPage.tsx
index 849049bc2..811d7e34b 100644
--- a/apps/edr-freight-web/backoffice/src/pages/auth/LoginPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/auth/LoginPage.tsx
@@ -14,25 +14,13 @@ import {
   Title,
 } from "@mantine/core";
 import { AlertCircle, ArrowLeft } from "lucide-react";
-import { useNavigate } from "react-router-dom";
+import { Link, useNavigate } from "react-router-dom";
 
 import { useAuth } from "@/auth/useAuth";
 import AuthShell from "@/components/auth/AuthShell";
+import { normaliseIdentifier } from "@/utils/identifier";
 import { extractApiError } from "@/utils/result";
 
-/** Normalise Ethiopian local phone (09…/07…) to E.164; pass email through unchanged. */
-const normaliseIdentifier = (raw: string): string => {
-  const v = raw.trim();
-  const digits = v.replace(/\D/g, "");
-  if (digits.length >= 9 && (v.startsWith("0") || v.startsWith("+251"))) {
-    const local = digits.startsWith("251")
-      ? digits.slice(3)
-      : digits.replace(/^0/, "");
-    return `+251${local}`;
-  }
-  return v.toLowerCase();
-};
-
 const EDR_LOGO = "/assets/logo.svg";
 
 const LoginPage = () => {
@@ -111,14 +99,24 @@ const LoginPage = () => {
           onChange={(event) => setIdentifier(event.target.value)}
         />
 
-        <PasswordInput
-          label="Password"
-          placeholder="Enter your password"
-          required
-          disabled={submitting}
-          value={password}
-          onChange={(event) => setPassword(event.target.value)}
-        />
+        <div>
+          <div className="mb-1.5 flex items-center justify-between">
+            <span className="text-sm font-medium">Password</span>
+            <Link
+              to="/forgot-password"
+              className="text-xs font-semibold text-primary hover:underline"
+            >
+              Forgot password?
+            </Link>
+          </div>
+          <PasswordInput
+            placeholder="Enter your password"
+            required
+            disabled={submitting}
+            value={password}
+            onChange={(event) => setPassword(event.target.value)}
+          />
+        </div>
 
         {error ? (
           <Alert color="red" variant="light" icon={<AlertCircle size={18} />}>
diff --git a/apps/edr-freight-web/backoffice/src/utils/identifier.ts b/apps/edr-freight-web/backoffice/src/utils/identifier.ts
new file mode 100644
index 000000000..72677f73c
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/utils/identifier.ts
@@ -0,0 +1,22 @@
+/** Normalise Ethiopian local phone (09…/07…) to E.164; pass email through unchanged. */
+export function normaliseIdentifier(raw: string): string {
+  const v = raw.trim();
+  const digits = v.replace(/\D/g, "");
+  if (digits.length >= 9 && (v.startsWith("0") || v.startsWith("+251"))) {
+    const local = digits.startsWith("251") ? digits.slice(3) : digits.replace(/^0/, "");
+    return `+251${local}`;
+  }
+  return v.toLowerCase();
+}
+
+/** Mask all but the first 7 chars of an E.164 phone for display. */
+export const maskPhone = (p: string) =>
+  p.length > 4 ? `${p.slice(0, 7)}${"*".repeat(Math.max(0, p.length - 7))}` : p;
+
+/** Mask the local part of an email for display (j***e@example.com). */
+export const maskEmail = (email: string) => {
+  const [local, domain] = email.split("@");
+  if (!local || !domain) return email;
+  if (local.length <= 2) return `${local[0] ?? ""}***@${domain}`;
+  return `${local[0]}***${local[local.length - 1]}@${domain}`;
+};
diff --git a/apps/edr-freight-web/backoffice/src/utils/passwordSchema.ts b/apps/edr-freight-web/backoffice/src/utils/passwordSchema.ts
new file mode 100644
index 000000000..207d9dc2b
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/utils/passwordSchema.ts
@@ -0,0 +1,38 @@
+import { z } from "zod";
+
+/** Live checklist shown under the password field. Mirrors {@link passwordField}. */
+export const passwordRequirements = [
+  { label: "At least 8 characters", test: (v: string) => v.length >= 8 },
+  { label: "One uppercase letter", test: (v: string) => /[A-Z]/.test(v) },
+  { label: "One lowercase letter", test: (v: string) => /[a-z]/.test(v) },
+  { label: "One number", test: (v: string) => /\d/.test(v) },
+  {
+    label: "One special character",
+    test: (v: string) => /[^A-Za-z0-9]/.test(v),
+  },
+] as const;
+
+/**
+ * Must stay in step with IAM's `@IsStrongPassword()` on `InitialResetPasswordDto`
+ * — a password this accepts but the API rejects surfaces as an opaque 400.
+ */
+export const passwordField = z
+  .string()
+  .min(8, "Password must be at least 8 characters")
+  .regex(/[A-Z]/, "Password must include an uppercase letter")
+  .regex(/[a-z]/, "Password must include a lowercase letter")
+  .regex(/\d/, "Password must include a number")
+  .regex(/[^A-Za-z0-9]/, "Password must include a special character");
+
+export const confirmPasswordField = z
+  .string()
+  .min(1, "Please confirm your password");
+
+export const samePassword = (data: {
+  password: string;
+  confirmPassword: string;
+}) => data.password === data.confirmPassword;
+
+/** Every requirement in {@link passwordRequirements} is satisfied. */
+export const meetsAllRequirements = (value: string) =>
+  passwordRequirements.every((r) => r.test(value));

From 6cb921e617d39728630027f7fd08bf666e6b7340 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 20 Jul 2026 07:41:25 +0000
Subject: [PATCH 10/15] fix: 194 and 183 plane takss

---
 .../validators/is-tin.validator.spec.ts       | 54 +++++++++++++++++++
 .../src/common/validators/is-tin.validator.ts | 54 +++++++++++++++++++
 .../modules/companies/companies.repository.ts |  8 ++-
 .../dto/create-company-with-profile.dto.ts    |  3 +-
 .../companies/dto/create-company.dto.ts       |  5 +-
 .../modules/companies/dto/fetch-etrade.dto.ts |  5 +-
 .../companies/dto/list-companies-query.dto.ts | 15 ++++++
 .../companies/dto/update-profile.dto.ts       |  5 +-
 .../src/pages/customers/CustomersPage.tsx     | 38 +++++++++++--
 .../backoffice/src/types/customer.ts          |  2 +
 .../accounts/companyProfileForm/schema.ts     |  2 +-
 .../on_boarding/TransportrOnBoarding.tsx      |  4 +-
 .../src/pages/settings/TabCompanyProfile.tsx  |  2 +-
 13 files changed, 180 insertions(+), 17 deletions(-)
 create mode 100644 apps/edr-freight-api/src/common/validators/is-tin.validator.spec.ts
 create mode 100644 apps/edr-freight-api/src/common/validators/is-tin.validator.ts

diff --git a/apps/edr-freight-api/src/common/validators/is-tin.validator.spec.ts b/apps/edr-freight-api/src/common/validators/is-tin.validator.spec.ts
new file mode 100644
index 000000000..cf6ca7a6e
--- /dev/null
+++ b/apps/edr-freight-api/src/common/validators/is-tin.validator.spec.ts
@@ -0,0 +1,54 @@
+import {
+  validate,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+} from 'class-validator';
+import { IsTin, normalizeTin } from './is-tin.validator';
+
+class Required {
+  @IsString()
+  @IsNotEmpty()
+  @IsTin({ message: 'TIN must be exactly 10 digits' })
+  tin!: string;
+}
+
+class Optional {
+  @IsOptional()
+  @IsString()
+  @IsTin({ message: 'TIN must be exactly 10 digits' })
+  tin?: string;
+}
+
+async function errs(cls: any, tin: any) {
+  const o = new cls();
+  o.tin = tin;
+  return (await validate(o)).length;
+}
+
+describe('IsTin', () => {
+  it('accepts a real 10-digit TIN', async () => {
+    expect(await errs(Required, '0012345678')).toBe(0);
+  });
+
+  it.each([
+    ['letters', 'ABCDEFGHIJ'],
+    ['symbols', '!!!!!!!!!!'],
+    ['too short', '123'],
+    ['too long', '12345678901'],
+    ['draft TIN', 'D123456789'],
+    ['spaced', '012 345678'],
+  ])('rejects %s', async (_label, value) => {
+    expect(await errs(Required, value)).toBeGreaterThan(0);
+  });
+
+  it('rejects empty on the required DTO but allows omission on the optional one', async () => {
+    expect(await errs(Required, '')).toBeGreaterThan(0);
+    expect(await errs(Optional, undefined)).toBe(0);
+  });
+
+  it('normalizes messy input', () => {
+    expect(normalizeTin(' 001-234-5678 ')).toBe('0012345678');
+    expect(normalizeTin('')).toBe('');
+  });
+});
diff --git a/apps/edr-freight-api/src/common/validators/is-tin.validator.ts b/apps/edr-freight-api/src/common/validators/is-tin.validator.ts
new file mode 100644
index 000000000..9396a884d
--- /dev/null
+++ b/apps/edr-freight-api/src/common/validators/is-tin.validator.ts
@@ -0,0 +1,54 @@
+import {
+  registerDecorator,
+  ValidationArguments,
+  ValidationOptions,
+  ValidatorConstraint,
+  ValidatorConstraintInterface,
+} from 'class-validator';
+
+/** An Ethiopian TIN is exactly 10 digits. */
+export const TIN_REGEX = /^\d{10}$/;
+
+/**
+ * Draft companies carry a placeholder TIN ("D" + 9 digits) minted server-side by
+ * CompaniesService.generateDraftTin(), because the column is NOT NULL + unique.
+ * Those never travel through a DTO, so this constraint deliberately rejects them
+ * — a "D…" value arriving on a request body is client-supplied and invalid.
+ */
+@ValidatorConstraint({ name: 'IsTin', async: false })
+export class IsTinConstraint implements ValidatorConstraintInterface {
+  validate(value: unknown): boolean {
+    // Empty is allowed here; pair with @IsOptional / @IsNotEmpty as needed.
+    if (value === undefined || value === null || value === '') return true;
+    if (typeof value !== 'string') return false;
+    return TIN_REGEX.test(value);
+  }
+
+  defaultMessage(args: ValidationArguments): string {
+    return `${args.property} must be exactly 10 digits`;
+  }
+}
+
+/** Class-validator decorator enforcing the 10-digit TIN format. */
+export function IsTin(validationOptions?: ValidationOptions) {
+  return function (object: object, propertyName: string) {
+    registerDecorator({
+      target: object.constructor,
+      propertyName,
+      options: validationOptions,
+      constraints: [],
+      validator: IsTinConstraint,
+    });
+  };
+}
+
+/**
+ * Strip everything that isn't a digit and cap at 10 characters. Tolerant —
+ * never throws; returns the value unchanged when empty/nullish.
+ */
+export function normalizeTin(
+  value: string | null | undefined,
+): string | null | undefined {
+  if (value === undefined || value === null || value === '') return value;
+  return value.replace(/\D/g, '').slice(0, 10);
+}
diff --git a/apps/edr-freight-api/src/modules/companies/companies.repository.ts b/apps/edr-freight-api/src/modules/companies/companies.repository.ts
index 6a0365854..b02f38380 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.repository.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.repository.ts
@@ -67,6 +67,8 @@ export class CompaniesRepository extends BaseRepository<Company> {
       kind,
       status,
       onboardingCompleted,
+      sortBy = 'name',
+      sortOrder = 'ASC',
     } = query;
 
     const qb = this.repository
@@ -113,8 +115,12 @@ export class CompaniesRepository extends BaseRepository<Company> {
       );
     }
 
+    // sortBy is whitelisted by @IsIn on the DTO, so it is safe to interpolate.
     const [items, total] = await qb
-      .orderBy('company.name', 'ASC')
+      .orderBy(`company.${sortBy}`, sortOrder)
+      // Names are not unique and createdAt can tie on bulk imports; the id
+      // tiebreaker keeps paging stable instead of dropping/repeating rows.
+      .addOrderBy('company.id', 'ASC')
       .skip((page - 1) * pageSize)
       .take(pageSize)
       .getManyAndCount();
diff --git a/apps/edr-freight-api/src/modules/companies/dto/create-company-with-profile.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/create-company-with-profile.dto.ts
index eb32f72ae..7816572ec 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/create-company-with-profile.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/create-company-with-profile.dto.ts
@@ -3,6 +3,7 @@ import { Type } from 'class-transformer';
 import { CompanyType } from '../entities/company.entity';
 import { ProfileType } from '../entities/company-profile.entity';
 import { IsValidPhone } from '../../../common/validators/is-phone-number.validator';
+import { IsTin } from '../../../common/validators/is-tin.validator';
 
 export class CompanyProfileInputDto {
   @IsEnum(ProfileType)
@@ -45,7 +46,7 @@ export class CreateCompanyWithProfileDto {
 
   @IsOptional()
   @IsString()
-  @MaxLength(10)
+  @IsTin({ message: 'TIN must be exactly 10 digits' })
   tin?: string;
 
   @IsOptional()
diff --git a/apps/edr-freight-api/src/modules/companies/dto/create-company.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/create-company.dto.ts
index a56ea5ad8..be911b3ec 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/create-company.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/create-company.dto.ts
@@ -1,6 +1,7 @@
-import { IsString, IsNotEmpty, IsOptional, IsEnum, MaxLength, Length, IsEmail } from 'class-validator';
+import { IsString, IsNotEmpty, IsOptional, IsEnum, MaxLength, IsEmail } from 'class-validator';
 import { CompanyType, CompanyStatus } from '../entities/company.entity';
 import { IsValidPhone } from '../../../common/validators/is-phone-number.validator';
+import { IsTin } from '../../../common/validators/is-tin.validator';
 
 export class CreateCompanyDto {
   @IsString()
@@ -17,7 +18,7 @@ export class CreateCompanyDto {
 
   @IsString()
   @IsNotEmpty()
-  @Length(10, 10, { message: 'TIN must be exactly 10 digits' })
+  @IsTin({ message: 'TIN must be exactly 10 digits' })
   tin!: string;
 
   @IsOptional()
diff --git a/apps/edr-freight-api/src/modules/companies/dto/fetch-etrade.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/fetch-etrade.dto.ts
index 2eb37c92d..466c03ed6 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/fetch-etrade.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/fetch-etrade.dto.ts
@@ -1,8 +1,9 @@
-import { IsString, IsNotEmpty, Length } from "class-validator";
+import { IsString, IsNotEmpty } from "class-validator";
+import { IsTin } from "../../../common/validators/is-tin.validator";
 
 export class FetchETradeDto {
   @IsString()
   @IsNotEmpty()
-  @Length(10, 10, { message: "TIN must be exactly 10 digits" })
+  @IsTin({ message: "TIN must be exactly 10 digits" })
   tin!: string;
 }
diff --git a/apps/edr-freight-api/src/modules/companies/dto/list-companies-query.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/list-companies-query.dto.ts
index adaa12479..8b5083e5f 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/list-companies-query.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/list-companies-query.dto.ts
@@ -47,4 +47,19 @@ export class ListCompaniesQueryDto {
   @Transform(({ value }: { value: unknown }) => value === "true" || value === true)
   @IsBoolean()
   onboardingCompleted?: boolean;
+
+  @ApiPropertyOptional({
+    enum: ["name", "createdAt", "updatedAt"],
+    default: "name",
+    description: "Column to order by. Defaults to name for backwards compatibility.",
+  })
+  @IsOptional()
+  @IsIn(["name", "createdAt", "updatedAt"])
+  sortBy?: "name" | "createdAt" | "updatedAt";
+
+  @ApiPropertyOptional({ enum: ["ASC", "DESC"], default: "ASC" })
+  @IsOptional()
+  @Transform(({ value }: { value: unknown }) => String(value).toUpperCase())
+  @IsIn(["ASC", "DESC"])
+  sortOrder?: "ASC" | "DESC";
 }
diff --git a/apps/edr-freight-api/src/modules/companies/dto/update-profile.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/update-profile.dto.ts
index 9fd8f28ae..a1b1ac9df 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/update-profile.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/update-profile.dto.ts
@@ -1,6 +1,7 @@
-import { IsString, IsOptional, IsEmail, MaxLength, Length, IsEnum } from 'class-validator';
+import { IsString, IsOptional, IsEmail, MaxLength, IsEnum } from 'class-validator';
 import { CompanyNationality } from '../entities/company.entity';
 import { IsValidPhone } from '../../../common/validators/is-phone-number.validator';
+import { IsTin } from '../../../common/validators/is-tin.validator';
 
 export class UpdateProfileDto {
   @IsOptional()
@@ -34,7 +35,7 @@ export class UpdateProfileDto {
 
   @IsOptional()
   @IsString()
-  @Length(10, 10, { message: 'TIN must be exactly 10 digits' })
+  @IsTin({ message: 'TIN must be exactly 10 digits' })
   tin?: string;
 
   @IsOptional()
diff --git a/apps/edr-freight-web/backoffice/src/pages/customers/CustomersPage.tsx b/apps/edr-freight-web/backoffice/src/pages/customers/CustomersPage.tsx
index 89325ae79..c1312a6ae 100644
--- a/apps/edr-freight-web/backoffice/src/pages/customers/CustomersPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/customers/CustomersPage.tsx
@@ -5,6 +5,7 @@ import {
   Card,
   Group,
   SegmentedControl,
+  Select,
   Stack,
   Text,
   TextInput,
@@ -63,22 +64,35 @@ const VIEW_FILTERS: Record<
   active: { status: "active" },
 };
 
+const SORT_OPTIONS = [
+  { value: "createdAt:DESC", label: "Newest first" },
+  { value: "createdAt:ASC", label: "Oldest first" },
+  { value: "name:ASC", label: "Name (A–Z)" },
+  { value: "name:DESC", label: "Name (Z–A)" },
+] as const;
+
 export default function CustomersPage() {
   const navigate = useNavigate();
   const { pagination, setPagination } = usePagination({ pageSize: 10 });
   const [query, setQuery] = useState("");
   const [debouncedQuery] = useDebouncedValue(query, 300);
   const [view, setView] = useState<CustomerView>("all");
+  const [sort, setSort] = useState<string>("createdAt:DESC");
 
-  const filter = useMemo(
-    () => ({
+  const filter = useMemo(() => {
+    const [sortBy, sortOrder] = sort.split(":") as [
+      "name" | "createdAt" | "updatedAt",
+      "ASC" | "DESC",
+    ];
+    return {
       page: pagination.pageIndex + 1,
       pageSize: pagination.pageSize,
       search: debouncedQuery,
+      sortBy,
+      sortOrder,
       ...VIEW_FILTERS[view],
-    }),
-    [pagination.pageIndex, pagination.pageSize, debouncedQuery, view],
-  );
+    };
+  }, [pagination.pageIndex, pagination.pageSize, debouncedQuery, view, sort]);
 
   const { data: stats } = useQuery(api.customers.stats.queryOptions({ input: {} }));
 
@@ -291,6 +305,20 @@ export default function CustomersPage() {
                   { label: "Active", value: "active" },
                 ]}
               />
+              <Select
+                size="sm"
+                radius="md"
+                w={160}
+                allowDeselect={false}
+                aria-label="Sort customers"
+                value={sort}
+                onChange={(v) => {
+                  if (!v) return;
+                  setSort(v);
+                  setPagination((prev) => ({ ...prev, pageIndex: 0 }));
+                }}
+                data={SORT_OPTIONS.map((o) => ({ ...o }))}
+              />
               <Text size="sm" c="dimmed">
                 {total} record{total !== 1 ? "s" : ""}
               </Text>
diff --git a/apps/edr-freight-web/backoffice/src/types/customer.ts b/apps/edr-freight-web/backoffice/src/types/customer.ts
index ef88403a9..a66d82a28 100644
--- a/apps/edr-freight-web/backoffice/src/types/customer.ts
+++ b/apps/edr-freight-web/backoffice/src/types/customer.ts
@@ -188,6 +188,8 @@ export interface CompanyListFilter {
   status?: CompanyStatus;
   /** `true` = submitted applications only; `false` = drafts only; omit for both. */
   onboardingCompleted?: boolean;
+  sortBy?: "name" | "createdAt" | "updatedAt";
+  sortOrder?: "ASC" | "DESC";
 }
 
 /** Standard paginated list envelope (matches the bookings service shape). */
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts
index 56a2bd57f..44c2cdec1 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts
@@ -21,7 +21,7 @@ export const onboardingSchema = z.object({
   // Derived from the eTrade address parts (kebele/woreda/zone/region); no
   // standalone input — the granular fields live in the registration section.
   companyAddress: z.string().optional(),
-  tinNumber: z.string().length(10, "TIN must be exactly 10 digits"),
+  tinNumber: z.string().regex(/^\d{10}$/, "TIN must be exactly 10 digits"),
   vatNumber: z
     .string()
     .min(1, "VAT number is required")
diff --git a/apps/edr-freight-web/portal/src/pages/customers/on_boarding/TransportrOnBoarding.tsx b/apps/edr-freight-web/portal/src/pages/customers/on_boarding/TransportrOnBoarding.tsx
index 20bd2249d..77b5d4ecd 100644
--- a/apps/edr-freight-web/portal/src/pages/customers/on_boarding/TransportrOnBoarding.tsx
+++ b/apps/edr-freight-web/portal/src/pages/customers/on_boarding/TransportrOnBoarding.tsx
@@ -36,7 +36,7 @@ const schema = z.object({
 
   // TRANSPORT
   fanNumber: z.string().min(1),
-  tinNumber: z.string().min(1),
+  tinNumber: z.string().regex(/^\d{10}$/, "TIN must be exactly 10 digits"),
 
   truckType: z.enum([
     "Casoni",
@@ -185,7 +185,7 @@ export default function TransporterOnboarding() {
 
                 <Field data-invalid={!!errors.tinNumber}>
                   <FieldLabel>TIN Number</FieldLabel>
-                  <Input {...register("tinNumber")} />
+                  <Input maxLength={10} inputMode="numeric" {...register("tinNumber")} />
                   <FieldError errors={[errors.tinNumber]} />
                 </Field>
               </div>
diff --git a/apps/edr-freight-web/portal/src/pages/settings/TabCompanyProfile.tsx b/apps/edr-freight-web/portal/src/pages/settings/TabCompanyProfile.tsx
index 27011a9d7..597dfa509 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabCompanyProfile.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabCompanyProfile.tsx
@@ -32,7 +32,7 @@ export const COMPANY_PROFILE_SCHEMA = z.object({
     .refine(isValidPhone, "Enter a valid phone number"),
   companyLocation: z.string().min(1, "Location is required"),
   companyAddress: z.string().min(1, "Address is required"),
-  tinNumber: z.string().length(10, "TIN must be exactly 10 digits"),
+  tinNumber: z.string().regex(/^\d{10}$/, "TIN must be exactly 10 digits"),
   fanNumber: z.string().length(16, "FAN must be exactly 16 digits"),
   vatNumber: z
     .string()

From 38bccaccf9b3472e3ced5ec4a998beb8c9e425c1 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 20 Jul 2026 08:19:59 +0000
Subject: [PATCH 11/15] fix: normalized the region and logged the otp properly

---
 apps/edr-freight-api/src/app.module.ts        |   2 +
 .../2400000000000-NormalizeCompanyRegions.ts  |  77 +++++++++
 .../companies/dto/update-profile.dto.ts       |  13 +-
 .../companies/services/etrade.service.ts      |   7 +-
 .../services/region-normalization.spec.ts     |  54 +++++++
 .../src/modules/health/health.controller.ts   | 108 +++++++++++++
 .../src/modules/health/health.module.ts       |  14 ++
 .../modules/notifications/broker.util.spec.ts |  90 +++++++++++
 .../src/modules/notifications/broker.util.ts  |  92 +++++++++++
 .../notifications/email-client.service.ts     |  36 +++--
 .../notifications/sms-client.service.ts       |  64 +++++---
 .../src/modules/otp/otp.controller.ts         |   8 +-
 .../src/modules/otp/otp.service.spec.ts       |  29 +++-
 .../src/modules/otp/otp.service.ts            | 150 ++++++++++++++++--
 .../src/pages/accounts/CompanyProfileForm.tsx |  28 +++-
 .../accounts/companyProfileForm/schema.ts     |   5 +-
 .../src/freight/ethiopian-regions.catalog.ts  |  97 +++++++++++
 packages/types/src/freight/index.ts           |   1 +
 18 files changed, 812 insertions(+), 63 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/2400000000000-NormalizeCompanyRegions.ts
 create mode 100644 apps/edr-freight-api/src/modules/companies/services/region-normalization.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/health/health.controller.ts
 create mode 100644 apps/edr-freight-api/src/modules/health/health.module.ts
 create mode 100644 apps/edr-freight-api/src/modules/notifications/broker.util.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/notifications/broker.util.ts
 create mode 100644 packages/types/src/freight/ethiopian-regions.catalog.ts

diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index a347b163b..3ca5f6cb1 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -44,6 +44,7 @@ import { FileUploadSettingsModule } from "./modules/file-upload-settings/file-up
 import { DropdownSettingsModule } from "./modules/dropdown-settings/dropdown-settings.module";
 import { ContractTemplatesModule } from "./modules/contract-templates/contract-templates.module";
 import { OtpModule } from "./modules/otp/otp.module";
+import { HealthModule } from "./modules/health/health.module";
 import { RuleEngineModule } from "./modules/rule-engine/rule-engine.module";
 import { BackofficeModule } from "./modules/backoffice/backoffice.module";
 import { DemoPermissionsModule } from "./modules/demo-permissions/demo-permissions.module";
@@ -166,6 +167,7 @@ import { LoggerMiddleware } from "./logger.middleware";
     DropdownSettingsModule,
     ContractTemplatesModule,
     OtpModule,
+    HealthModule,
     RuleEngineModule,
     BackofficeModule,
     DemoPermissionsModule,
diff --git a/apps/edr-freight-api/src/migrations/2400000000000-NormalizeCompanyRegions.ts b/apps/edr-freight-api/src/migrations/2400000000000-NormalizeCompanyRegions.ts
new file mode 100644
index 000000000..b3369b82d
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/2400000000000-NormalizeCompanyRegions.ts
@@ -0,0 +1,77 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * `freight.companies.region` was free text until region became a closed set
+ * (see ETHIOPIAN_REGIONS in @edr/types). This normalizes the rows written under
+ * the old rules so they satisfy the new dropdown.
+ *
+ * Two classes of bad data exist, handled differently:
+ *
+ *  - Unambiguous spelling/case drift ("Addis ababa", "oromoia") — rewritten to
+ *    the canonical spelling.
+ *  - Values that are not regions at all ("Arba Minch", a city), and rows whose
+ *    region contradicts their own zone/woreda — set to NULL. These are NOT
+ *    guessed at: inferring "Gurage/Meskan" means Central Ethiopia would silently
+ *    overwrite what the customer actually submitted. NULL surfaces the gap and
+ *    the required dropdown forces a deliberate pick on next edit.
+ */
+export class NormalizeCompanyRegions2400000000000 implements MigrationInterface {
+  name = 'NormalizeCompanyRegions2400000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // Canonical spellings — case/whitespace insensitive, safe to re-run.
+    await queryRunner.query(`
+      UPDATE freight.companies
+         SET region = v.canonical
+        FROM (VALUES
+          ('addis ababa',       'Addis Ababa'),
+          ('addis abeba',       'Addis Ababa'),
+          ('addisababa',        'Addis Ababa'),
+          ('oromia',            'Oromia'),
+          ('oromoia',           'Oromia'),
+          ('oromiya',           'Oromia'),
+          ('amhara',            'Amhara'),
+          ('somali',            'Somali'),
+          ('afar',              'Afar'),
+          ('tigray',            'Tigray'),
+          ('tigrai',            'Tigray'),
+          ('sidama',            'Sidama'),
+          ('harari',            'Harari'),
+          ('gambela',           'Gambela'),
+          ('gambella',          'Gambela'),
+          ('dire dawa',         'Dire Dawa'),
+          ('benishangul-gumuz', 'Benishangul-Gumuz'),
+          ('benishangul gumuz', 'Benishangul-Gumuz'),
+          ('central ethiopia',  'Central Ethiopia'),
+          ('south ethiopia',    'South Ethiopia')
+        ) AS v(variant, canonical)
+       WHERE freight.companies.region IS NOT NULL
+         AND lower(regexp_replace(btrim(freight.companies.region), '\\s+', ' ', 'g')) = v.variant
+         AND freight.companies.region <> v.canonical
+    `);
+
+    // Anything still outside the canonical set is unresolvable — null it.
+    await queryRunner.query(`
+      UPDATE freight.companies
+         SET region = NULL
+       WHERE region IS NOT NULL
+         AND region <> ''
+         AND region NOT IN (
+           'Addis Ababa','Afar','Amhara','Benishangul-Gumuz','Central Ethiopia',
+           'Dire Dawa','Gambela','Harari','Oromia','Sidama','Somali',
+           'South Ethiopia','South West Ethiopia Peoples''','Tigray'
+         )
+    `);
+
+    // Normalize empty string to NULL so "unset" has one representation.
+    await queryRunner.query(`
+      UPDATE freight.companies SET region = NULL WHERE region = ''
+    `);
+  }
+
+  public async down(): Promise<void> {
+    // Irreversible by design: the original free-text values are not retained
+    // anywhere, so there is nothing to restore. Rolling back the code is safe —
+    // the column is still a nullable varchar(100) and accepts free text again.
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/companies/dto/update-profile.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/update-profile.dto.ts
index a1b1ac9df..ba3e27aeb 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/update-profile.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/update-profile.dto.ts
@@ -1,4 +1,5 @@
-import { IsString, IsOptional, IsEmail, MaxLength, IsEnum } from 'class-validator';
+import { IsString, IsOptional, IsEmail, MaxLength, IsEnum, IsIn } from 'class-validator';
+import { ETHIOPIAN_REGIONS, type EthiopianRegion } from '@edr/types';
 import { CompanyNationality } from '../entities/company.entity';
 import { IsValidPhone } from '../../../common/validators/is-phone-number.validator';
 import { IsTin } from '../../../common/validators/is-tin.validator';
@@ -138,10 +139,14 @@ export class UpdateProfileDto {
   @MaxLength(50)
   renewedTo?: string;
 
+  // Zone/woreda/kebele below stay free text: there is no authoritative dataset
+  // of Ethiopian zones/woredas/kebeles in the platform yet, and eTrade returns
+  // them uncoded. Only region is a closed set today.
   @IsOptional()
-  @IsString()
-  @MaxLength(100)
-  region?: string;
+  @IsIn(ETHIOPIAN_REGIONS as unknown as string[], {
+    message: "region must be a recognised Ethiopian region",
+  })
+  region?: EthiopianRegion;
 
   @IsOptional()
   @IsString()
diff --git a/apps/edr-freight-api/src/modules/companies/services/etrade.service.ts b/apps/edr-freight-api/src/modules/companies/services/etrade.service.ts
index b588c241f..51bdb2df6 100644
--- a/apps/edr-freight-api/src/modules/companies/services/etrade.service.ts
+++ b/apps/edr-freight-api/src/modules/companies/services/etrade.service.ts
@@ -6,6 +6,7 @@ import {
   ETradeCompanyInfo,
   ETradeBusinessInfo,
   CompanyRegistrationData,
+  normalizeRegion,
 } from "@edr/types";
 
 @Injectable()
@@ -108,7 +109,11 @@ export class ETradeService {
       renewedFrom: businessInfo.RenewedFrom,
       renewalDate: businessInfo.RenewalDate,
       renewedTo: businessInfo.RenewedTo,
-      region: businessInfo.AddressInfo?.Region || "",
+      // eTrade returns uncoded uppercase text and sometimes a zone name in the
+      // Region slot. Map it onto the canonical list; an unresolved value yields
+      // "" so the form asks the user to pick rather than failing validation on
+      // save with a value they never typed.
+      region: normalizeRegion(businessInfo.AddressInfo?.Region) ?? "",
       zone: businessInfo.AddressInfo?.Zone || "",
       woreda: businessInfo.AddressInfo?.Woreda || "",
       kebele: businessInfo.AddressInfo?.Kebele || "",
diff --git a/apps/edr-freight-api/src/modules/companies/services/region-normalization.spec.ts b/apps/edr-freight-api/src/modules/companies/services/region-normalization.spec.ts
new file mode 100644
index 000000000..910b3199a
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/companies/services/region-normalization.spec.ts
@@ -0,0 +1,54 @@
+import { ETHIOPIAN_REGIONS, normalizeRegion } from '@edr/types';
+
+/**
+ * normalizeRegion lives in @edr/types (no jest there), but it exists to keep
+ * eTrade autofill from feeding UpdateProfileDto a region its @IsIn will reject.
+ * That contract is an API concern, so it is guarded here.
+ */
+describe('normalizeRegion', () => {
+  it('passes through every canonical region unchanged', () => {
+    for (const region of ETHIOPIAN_REGIONS) {
+      expect(normalizeRegion(region)).toBe(region);
+    }
+  });
+
+  it.each([
+    ['ADDIS ABABA', 'Addis Ababa'],
+    ['Addis ababa', 'Addis Ababa'],
+    ['  addis   ababa  ', 'Addis Ababa'],
+    ['oromoia', 'Oromia'],
+    ['OROMIYA', 'Oromia'],
+    ['gambella', 'Gambela'],
+    ['TIGRAI', 'Tigray'],
+    ['benishangul gumuz', 'Benishangul-Gumuz'],
+  ])('resolves the variant %s', (input, expected) => {
+    expect(normalizeRegion(input)).toBe(expected);
+  });
+
+  it('maps a zone name in the region slot back to its parent region', () => {
+    // eTrade's own placeholder data does this — "EASTERN TIGRAY" is a zone.
+    expect(normalizeRegion('EASTERN TIGRAY')).toBe('Tigray');
+    expect(normalizeRegion('North Wollo')).toBe('Amhara');
+  });
+
+  it.each([
+    ['a city, not a region', 'Arba Minch'],
+    ['unknown text', 'Nowhere Land'],
+    ['empty', ''],
+    ['whitespace only', '   '],
+    ['null', null],
+    ['undefined', undefined],
+  ])('returns null for %s rather than guessing', (_label, input) => {
+    expect(normalizeRegion(input as string | null | undefined)).toBeNull();
+  });
+
+  it('never returns a value outside the canonical set', () => {
+    const samples = ['ADDIS ABABA', 'oromoia', 'EASTERN TIGRAY', 'garbage', ''];
+    for (const s of samples) {
+      const out = normalizeRegion(s);
+      if (out !== null) {
+        expect(ETHIOPIAN_REGIONS).toContain(out);
+      }
+    }
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/health/health.controller.ts b/apps/edr-freight-api/src/modules/health/health.controller.ts
new file mode 100644
index 000000000..6b559f2e3
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/health/health.controller.ts
@@ -0,0 +1,108 @@
+// health.controller.ts
+
+import { Controller, Get, HttpStatus, Res } from "@nestjs/common";
+import { ApiOperation, ApiTags } from "@nestjs/swagger";
+import { InjectDataSource } from "@nestjs/typeorm";
+import { Public } from "@edr/api-common";
+import { Response } from "express";
+import { DataSource } from "typeorm";
+
+import { EmailClientService } from "../notifications/email-client.service";
+import { SmsClientService } from "../notifications/sms-client.service";
+
+type CheckStatus = "ok" | "error" | "unknown";
+
+/**
+ * Readiness normally stays green when only the broker is down.
+ *
+ * A 503 pulls the pod out of the load balancer, which would take booking,
+ * tracking and billing offline because SMS is unreachable — a strictly worse
+ * outcome than degraded notifications. The broker check is therefore reported,
+ * not enforced, and `READINESS_REQUIRES_BROKER=true` opts into hard-failing for
+ * deployments where a silent OTP black hole is the greater risk.
+ */
+const READINESS_REQUIRES_BROKER =
+  process.env.READINESS_REQUIRES_BROKER === "true";
+
+@ApiTags("Health")
+@Controller("health")
+export class HealthController {
+  constructor(
+    @InjectDataSource()
+    private readonly dataSource: DataSource,
+    private readonly smsClient: SmsClientService,
+    private readonly emailClient: EmailClientService,
+  ) {}
+
+  @Get()
+  @Public()
+  @ApiOperation({ summary: "Liveness probe" })
+  liveness() {
+    return { status: "ok", timestamp: new Date().toISOString() };
+  }
+
+  @Get("ready")
+  @Public()
+  @ApiOperation({
+    summary:
+      "Readiness probe — database plus SMS/email broker connectivity. Broker failures report as degraded unless READINESS_REQUIRES_BROKER=true.",
+  })
+  async readiness(@Res() res: Response) {
+    const startedAt = Date.now();
+
+    let database: { status: CheckStatus; latencyMs: number; error?: string };
+    try {
+      await this.dataSource.query("SELECT 1");
+      database = { status: "ok", latencyMs: Date.now() - startedAt };
+    } catch (error) {
+      database = {
+        status: "error",
+        latencyMs: Date.now() - startedAt,
+        error: error instanceof Error ? error.message : "Unknown error",
+      };
+    }
+
+    // `null` from the client means the connection manager was not reachable
+    // through Nest's internals — surfaced as "unknown" so a shape change in
+    // @nestjs/microservices degrades to honest ignorance, not a false "ok".
+    const toStatus = (connected: boolean | null): CheckStatus =>
+      connected === null ? "unknown" : connected ? "ok" : "error";
+
+    const broker = {
+      sms: { status: toStatus(this.smsClient.brokerConnected) },
+      email: { status: toStatus(this.emailClient.brokerConnected) },
+      // Every OTP, and every booking/billing notification, publishes through
+      // these. `error` here means codes are being generated and silently dropped.
+      enabled: process.env.RABBITMQ_ENABLED !== "false",
+    };
+
+    const brokerDown =
+      broker.sms.status === "error" || broker.email.status === "error";
+    const failed =
+      database.status === "error" ||
+      (READINESS_REQUIRES_BROKER && brokerDown);
+
+    const status = failed ? "error" : brokerDown ? "degraded" : "ok";
+
+    return res
+      .status(failed ? HttpStatus.SERVICE_UNAVAILABLE : HttpStatus.OK)
+      .json({
+        status,
+        timestamp: new Date().toISOString(),
+        checks: { database, broker },
+      });
+  }
+
+  @Get("info")
+  @Public()
+  @ApiOperation({ summary: "App info — version, environment, uptime" })
+  info() {
+    return {
+      name: "edr-freight-api",
+      version: process.env.npm_package_version ?? "1.0.0",
+      environment: process.env.NODE_ENV ?? "development",
+      uptimeSeconds: Math.floor(process.uptime()),
+      timestamp: new Date().toISOString(),
+    };
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/health/health.module.ts b/apps/edr-freight-api/src/modules/health/health.module.ts
new file mode 100644
index 000000000..572e5eb86
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/health/health.module.ts
@@ -0,0 +1,14 @@
+// health.module.ts
+
+import { Module } from "@nestjs/common";
+
+import { HealthController } from "./health.controller";
+import { NotificationsModule } from "../notifications/notifications.module";
+
+@Module({
+  // NotificationsModule exports the SMS/email clients; the readiness probe reads
+  // their broker connection state rather than opening a second connection.
+  imports: [NotificationsModule],
+  controllers: [HealthController],
+})
+export class HealthModule {}
diff --git a/apps/edr-freight-api/src/modules/notifications/broker.util.spec.ts b/apps/edr-freight-api/src/modules/notifications/broker.util.spec.ts
new file mode 100644
index 000000000..a6f73ac0a
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/notifications/broker.util.spec.ts
@@ -0,0 +1,90 @@
+import { Logger } from '@nestjs/common';
+import { ClientProxy } from '@nestjs/microservices';
+import { NEVER, Observable, throwError } from 'rxjs';
+
+import { isBrokerConnected, publishConfirmed } from './broker.util';
+
+/**
+ * `ClientProxy.emit()` returns a cold Observable that, for RMQ, completes without
+ * emitting once `dispatchEvent` settles — and rejects if the publish fails. These
+ * fakes reproduce each of those three shapes.
+ */
+function clientEmitting(source: Observable<unknown>): ClientProxy {
+  return { emit: jest.fn().mockReturnValue(source) } as unknown as ClientProxy;
+}
+
+describe('publishConfirmed', () => {
+  const logger = { error: jest.fn() } as unknown as Logger;
+
+  beforeEach(() => jest.clearAllMocks());
+
+  it('is true when the publish completes (broker confirmed)', async () => {
+    // Completes with no value — the success shape, and the case that throws
+    // EmptyError without a defaultIfEmpty.
+    const client = clientEmitting(new Observable<never>((s) => s.complete()));
+    await expect(publishConfirmed(client, 'send-sms', {}, logger)).resolves.toBe(true);
+  });
+
+  it('is false when the publish never settles, rather than hanging', async () => {
+    // A broker that is down: amqp-connection-manager buffers the publish and the
+    // promise would never resolve. The timeout is what stops one dead broker from
+    // hanging every caller of sendSms/sendEmail.
+    const client = clientEmitting(NEVER);
+    await expect(publishConfirmed(client, 'send-sms', {}, logger, 20)).resolves.toBe(
+      false,
+    );
+    expect(logger.error).toHaveBeenCalled();
+  });
+
+  it('is false when the publish errors', async () => {
+    const client = clientEmitting(throwError(() => new Error('channel closed')));
+    await expect(publishConfirmed(client, 'send-email', {}, logger)).resolves.toBe(
+      false,
+    );
+    expect(logger.error).toHaveBeenCalled();
+  });
+});
+
+describe('isBrokerConnected', () => {
+  /** Stands in for `ClientProxy.unwrap()`, which returns the AmqpConnectionManager. */
+  function clientUnwrapping(manager: unknown): ClientProxy {
+    return { unwrap: () => manager } as unknown as ClientProxy;
+  }
+
+  it('reports the connection manager state', () => {
+    expect(isBrokerConnected(clientUnwrapping({ isConnected: () => true }))).toBe(
+      true,
+    );
+    expect(isBrokerConnected(clientUnwrapping({ isConnected: () => false }))).toBe(
+      false,
+    );
+  });
+
+  it('is false when unwrap throws — the client never connected', () => {
+    // ClientRMQ.unwrap() throws "Not initialized" while its internal client is
+    // null, which is what a failed boot-time connect leaves behind. That is a
+    // real down signal and must not be softened to "unknown".
+    const uninitialised = {
+      unwrap: () => {
+        throw new Error('Not initialized. Please call the "connect" method first.');
+      },
+    } as unknown as ClientProxy;
+    expect(isBrokerConnected(uninitialised)).toBe(false);
+  });
+
+  it('is null — not a guess — when the manager lacks isConnected or it throws', () => {
+    // Guards the health endpoint against reporting "ok" if amqp-connection-manager
+    // or Nest changes shape and the accessor we rely on disappears.
+    expect(isBrokerConnected(clientUnwrapping(null))).toBeNull();
+    expect(isBrokerConnected(clientUnwrapping({}))).toBeNull();
+    expect(
+      isBrokerConnected(
+        clientUnwrapping({
+          isConnected: () => {
+            throw new Error('boom');
+          },
+        }),
+      ),
+    ).toBeNull();
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/notifications/broker.util.ts b/apps/edr-freight-api/src/modules/notifications/broker.util.ts
new file mode 100644
index 000000000..aa09d362e
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/notifications/broker.util.ts
@@ -0,0 +1,92 @@
+// broker.util.ts
+
+import { Logger } from "@nestjs/common";
+import { ClientProxy } from "@nestjs/microservices";
+import { defaultIfEmpty, lastValueFrom, timeout } from "rxjs";
+
+/**
+ * How long to wait for a publisher confirm before giving up on a message.
+ *
+ * Load-bearing, not a nicety: when the broker is unreachable
+ * amqp-connection-manager buffers the publish and retries it on reconnect, so the
+ * underlying promise never settles. Without a bound, one dead broker turns every
+ * caller of sendSms/sendEmail into a hung request.
+ */
+export const PUBLISH_CONFIRM_TIMEOUT_MS = Number(
+  process.env.RABBITMQ_PUBLISH_TIMEOUT_MS ?? 5000,
+);
+
+/**
+ * Publish an event and wait for RabbitMQ to confirm it.
+ *
+ * `ClientProxy.emit()` returns a *cold* Observable. Called without subscribing —
+ * as this codebase did everywhere — nothing forces the publish to be observed, so
+ * the caller reports success whether or not the broker ever accepted the message.
+ * Awaiting it drives `dispatchEvent`, which resolves only once
+ * amqp-connection-manager's ChannelWrapper has a publisher confirm.
+ *
+ * So `true` here means the broker took ownership of the message. It still says
+ * nothing about the consumer, the SMS gateway, or delivery to a handset — those
+ * remain outside this process's knowledge.
+ */
+export async function publishConfirmed(
+  client: ClientProxy,
+  pattern: string,
+  payload: unknown,
+  logger: Logger,
+  timeoutMs: number = PUBLISH_CONFIRM_TIMEOUT_MS,
+): Promise<boolean> {
+  try {
+    // `emit` completes without emitting a value, so lastValueFrom needs a default
+    // or it rejects with EmptyError on the success path.
+    await lastValueFrom(
+      client
+        .emit(pattern, payload)
+        .pipe(timeout(timeoutMs), defaultIfEmpty(undefined)),
+    );
+    return true;
+  } catch (error) {
+    logger.error(
+      `broker.publish.failed pattern='${pattern}' timeoutMs=${timeoutMs}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      error instanceof Error ? error.stack : undefined,
+    );
+    return false;
+  }
+}
+
+/**
+ * Whether the client's connection manager currently believes it is connected.
+ *
+ * Uses `ClientProxy.unwrap()` — Nest's public accessor for the underlying
+ * transport client, which for `ClientRMQ` is the `AmqpConnectionManager`. Calling
+ * `connect()` instead cannot answer this: it resolves against a *disconnected*
+ * manager too, so it never distinguishes up from down.
+ *
+ * Three outcomes, deliberately distinct:
+ *  - `false` when the manager reports disconnected, or when `unwrap()` throws
+ *    because the client was never initialised (a failed boot-time connect leaves
+ *    it null — genuinely down, not unknown);
+ *  - `null` when the manager exists but has no `isConnected`, i.e. the library
+ *    shape changed under us — the health endpoint reports "unknown" rather than
+ *    quietly claiming health;
+ *  - `true` only on an explicit positive from the manager.
+ */
+export function isBrokerConnected(client: ClientProxy): boolean | null {
+  let manager: unknown;
+  try {
+    manager = client.unwrap<unknown>();
+  } catch {
+    // "Not initialized. Please call the connect method first." — no connection
+    // was ever established, which is a real down signal, not an unknown one.
+    return false;
+  }
+  const probe = manager as { isConnected?: () => boolean } | null;
+  if (!probe || typeof probe.isConnected !== "function") return null;
+  try {
+    return probe.isConnected();
+  } catch {
+    return null;
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/notifications/email-client.service.ts b/apps/edr-freight-api/src/modules/notifications/email-client.service.ts
index 161b2486a..20a43d061 100644
--- a/apps/edr-freight-api/src/modules/notifications/email-client.service.ts
+++ b/apps/edr-freight-api/src/modules/notifications/email-client.service.ts
@@ -6,6 +6,7 @@ import {
 } from "@nestjs/common";
 import { ClientProxy } from "@nestjs/microservices";
 import { SendEmailDto } from "./dtos/email.dto";
+import { isBrokerConnected, publishConfirmed } from "./broker.util";
 
 @Injectable()
 export class EmailClientService implements OnApplicationBootstrap {
@@ -33,19 +34,34 @@ export class EmailClientService implements OnApplicationBootstrap {
       this.logger.warn(`RABBITMQ disabled — skipped EMAIL to=${dto.to}`);
       return { queued: false };
     }
-    this.emailClient.emit("send-email", {
-      to: dto.to,
-      subject: dto.subject,
-      text: dto.text,
-      html: dto.html,
-      appKey: "IFHCRS-LICENSE-MANAGEMENT",
-    });
-    // Fire-and-forget enqueue: confirms hand-off to RabbitMQ, NOT delivery.
+    const queued = await publishConfirmed(
+      this.emailClient,
+      "send-email",
+      {
+        to: dto.to,
+        subject: dto.subject,
+        text: dto.text,
+        html: dto.html,
+        appKey: "IFHCRS-LICENSE-MANAGEMENT",
+      },
+      this.logger,
+    );
+    // Publisher-confirmed: RabbitMQ has taken ownership of the message. Still NOT
+    // delivery — the consumer and the SMTP hop are downstream and invisible here.
     this.logger.log(
-      `EMAIL queued to RabbitMQ [${process.env.EMAIL_QUEUE ?? "email_queue"}] pattern='send-email'`,
+      `EMAIL publish to RabbitMQ [${process.env.EMAIL_QUEUE ?? "email_queue"}] pattern='send-email' confirmed=${queued}`,
     );
     // Recipient + content are PII — debug only.
     this.logger.debug(`EMAIL payload to=${dto.to} subject="${dto.subject}"`);
-    return { queued: true };
+    return { queued };
+  }
+
+  /**
+   * Connection state for the health endpoint. `null` means the broker client did
+   * not expose its manager — reported as "unknown" rather than assumed healthy.
+   */
+  get brokerConnected(): boolean | null {
+    if (!this.enabled) return false;
+    return isBrokerConnected(this.emailClient);
   }
 }
diff --git a/apps/edr-freight-api/src/modules/notifications/sms-client.service.ts b/apps/edr-freight-api/src/modules/notifications/sms-client.service.ts
index f94c0c20e..43e47f350 100644
--- a/apps/edr-freight-api/src/modules/notifications/sms-client.service.ts
+++ b/apps/edr-freight-api/src/modules/notifications/sms-client.service.ts
@@ -6,6 +6,7 @@ import {
 } from "@nestjs/common";
 import { ClientProxy } from "@nestjs/microservices";
 import { BulkMessagesDto, SingleMessageDto } from "./dtos/sms.dto";
+import { isBrokerConnected, publishConfirmed } from "./broker.util";
 
 @Injectable()
 export class SmsClientService implements OnApplicationBootstrap {
@@ -14,7 +15,7 @@ export class SmsClientService implements OnApplicationBootstrap {
   constructor(
     @Inject("SMS_SERVICE")
     private smsClient: ClientProxy,
-  ) {}
+  ) { }
 
   private readonly enabled = process.env.RABBITMQ_ENABLED !== "false";
 
@@ -26,7 +27,7 @@ export class SmsClientService implements OnApplicationBootstrap {
         this.logger.log("connected to SMS service");
       })
       .catch((err) => {
-        console.error("Error happened at SMS service", err);
+        this.logger.error("Error happened at SMS service", err);
       });
   }
 
@@ -35,34 +36,61 @@ export class SmsClientService implements OnApplicationBootstrap {
       this.logger.warn(`RABBITMQ disabled — skipped SMS`);
       return { queued: false };
     }
-    this.smsClient.emit("send-sms", {
-      to: dto.to,
-      text: dto.message,
-      appKey: "IFHCRS-LICENSE-MANAGEMENT",
-    });
-    // Fire-and-forget enqueue: confirms hand-off to RabbitMQ, NOT delivery.
+    const queued = await publishConfirmed(
+      this.smsClient,
+      "send-sms",
+      {
+        to: dto.to,
+        text: dto.message,
+        appKey: "IFHCRS-LICENSE-MANAGEMENT",
+      },
+      this.logger,
+    );
+    // Publisher-confirmed: RabbitMQ has taken ownership of the message. Still NOT
+    // delivery — the consumer, the SMS gateway and the carrier are all downstream
+    // of this and invisible from here.
     this.logger.log(
-      `SMS queued to RabbitMQ [${process.env.SMS_QUEUE ?? "sms_queue"}] pattern='send-sms'`,
+      `SMS publish to RabbitMQ [${process.env.SMS_QUEUE ?? "sms_queue"}] pattern='send-sms' confirmed=${queued}`,
     );
     // Recipient + content are PII — debug only.
     this.logger.debug(`SMS payload to=${dto.to} text="${dto.message}"`);
-    return { queued: true };
+    return { queued };
   }
 
   async sendBulkMessages(dto: BulkMessagesDto): Promise<{ queued: boolean }> {
     if (!this.enabled) {
-      this.logger.warn(`RABBITMQ disabled — skipped BULK SMS (${dto.messages?.length ?? 0} messages)`);
+      this.logger.warn(
+        `RABBITMQ disabled — skipped BULK SMS (${dto.messages?.length ?? 0} messages)`,
+      );
       return { queued: false };
     }
-    const messages = (dto.messages ?? []).map((m) => ({ to: m.to, text: m.message, from: m.from }));
-    this.smsClient.emit("ozeking-bulk-sms", {
-      messages,
-      appKey: "IFHCRS-LICENSE-MANAGEMENT",
-    });
+    const messages = (dto.messages ?? []).map((m) => ({
+      to: m.to,
+      text: m.message,
+      from: m.from,
+    }));
+    const queued = await publishConfirmed(
+      this.smsClient,
+      "ozeking-bulk-sms",
+      {
+        messages,
+        appKey: "IFHCRS-LICENSE-MANAGEMENT",
+      },
+      this.logger,
+    );
     this.logger.log(
-      `BULK SMS queued to RabbitMQ [${process.env.SMS_QUEUE ?? "sms_queue"}] pattern='ozeking-bulk-sms' count=${messages.length}`,
+      `BULK SMS publish to RabbitMQ [${process.env.SMS_QUEUE ?? "sms_queue"}] pattern='ozeking-bulk-sms' count=${messages.length} confirmed=${queued}`,
     );
     this.logger.debug(`BULK SMS payload messages=${JSON.stringify(messages)}`);
-    return { queued: true };
+    return { queued };
+  }
+
+  /**
+   * Connection state for the health endpoint. `null` means the broker client did
+   * not expose its manager — reported as "unknown" rather than assumed healthy.
+   */
+  get brokerConnected(): boolean | null {
+    if (!this.enabled) return false;
+    return isBrokerConnected(this.smsClient);
   }
 }
diff --git a/apps/edr-freight-api/src/modules/otp/otp.controller.ts b/apps/edr-freight-api/src/modules/otp/otp.controller.ts
index 5d12f91f9..6b0078429 100644
--- a/apps/edr-freight-api/src/modules/otp/otp.controller.ts
+++ b/apps/edr-freight-api/src/modules/otp/otp.controller.ts
@@ -41,7 +41,13 @@ export class OtpController {
     @Body("email")
     email?: string
   ) {
-    return this.otpService.sendOtp(toTarget(phone, email));
+    // `delivered` stays server-side: this route is @Public(), and whether our
+    // broker accepted the publish is infrastructure state an anonymous caller has
+    // no need for. It is on the `otp.dispatch` log line instead.
+    const { success, message } = await this.otpService.sendOtp(
+      toTarget(phone, email)
+    );
+    return { success, message };
   }
 
   // ---------------------------------------------------------------------------
diff --git a/apps/edr-freight-api/src/modules/otp/otp.service.spec.ts b/apps/edr-freight-api/src/modules/otp/otp.service.spec.ts
index 5f4afcfbd..c9d5c5714 100644
--- a/apps/edr-freight-api/src/modules/otp/otp.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/otp/otp.service.spec.ts
@@ -11,8 +11,15 @@ describe('normalizeOtpTarget', () => {
     expect(normalizeOtpTarget({ phone: '0712345678' }).phone).toBe('+251712345678');
   });
 
-  it('passes email targets through untouched', () => {
-    expect(normalizeOtpTarget({ email: 'a@b.com' })).toEqual({ email: 'a@b.com' });
+  it('canonicalises email case and surrounding whitespace to one key', () => {
+    const forms = ['a@b.com', 'A@B.com', '  a@B.COM  ', 'A@b.COM'];
+    const keys = forms.map((email) => normalizeOtpTarget({ email }).email);
+    expect(new Set(keys)).toEqual(new Set(['a@b.com']));
+  });
+
+  it('keeps an already-normalised email stable (idempotent)', () => {
+    const once = normalizeOtpTarget({ email: ' User@Example.COM ' }).email!;
+    expect(normalizeOtpTarget({ email: once }).email).toBe(once);
   });
 
   it('keeps an already-normalised number stable (idempotent)', () => {
@@ -40,8 +47,10 @@ describe('OtpService — send/verify agree across phone formats', () => {
         rows.delete(row.phone ?? row.email!);
       }),
     };
-    const sms = { sendSms: jest.fn().mockResolvedValue(undefined) };
-    const email = { sendEmail: jest.fn().mockResolvedValue(undefined) };
+    // Both clients return `{ queued }` — the service reads it to tell a published
+    // code apart from one the transport silently dropped.
+    const sms = { sendSms: jest.fn().mockResolvedValue({ queued: true }) };
+    const email = { sendEmail: jest.fn().mockResolvedValue({ queued: true }) };
     const service = new OtpService(repo as never, sms as never, email as never);
     return { service, rows };
   }
@@ -58,4 +67,16 @@ describe('OtpService — send/verify agree across phone formats', () => {
       service.verifyOtpForAction({ phone: '0986680099' }, stored),
     ).resolves.toEqual({ success: true });
   });
+
+  it('verifies a code sent to User@X.com when verify is called with user@x.com', async () => {
+    const { service, rows } = makeService();
+    await service.sendOtp({ email: '  User@Example.COM ' });
+    const stored = [...rows.values()][0]!.otp;
+
+    [...rows.values()][0]!.updatedAt = new Date();
+
+    await expect(
+      service.verifyOtpForAction({ email: 'user@example.com' }, stored),
+    ).resolves.toEqual({ success: true });
+  });
 });
diff --git a/apps/edr-freight-api/src/modules/otp/otp.service.ts b/apps/edr-freight-api/src/modules/otp/otp.service.ts
index 06d837065..5e91251c9 100644
--- a/apps/edr-freight-api/src/modules/otp/otp.service.ts
+++ b/apps/edr-freight-api/src/modules/otp/otp.service.ts
@@ -22,7 +22,18 @@ export type OtpTarget = { phone?: string; email?: string };
  * Email targets pass through untouched.
  */
 export function normalizeOtpTarget(target: OtpTarget): OtpTarget {
-  if (target.email || !target.phone) return target;
+  if (target.email) {
+    // Same contract as the phone branch below: the string stored on send and the
+    // one looked up on verify must be byte-identical, or the code is invisible to
+    // the verifier. Addresses reach us from a raw `@Body("email")` with no DTO or
+    // ValidationPipe, so `User@X.com`, `user@x.com` and a copy-paste with a
+    // trailing space are three different keys for one mailbox. Domains are
+    // case-insensitive (RFC 1035); local-parts are formally case-sensitive
+    // (RFC 5321 §2.4) but no mail provider in practice treats them so, and
+    // matching what users expect beats matching the letter of the spec here.
+    return { email: target.email.trim().toLowerCase() };
+  }
+  if (!target.phone) return target;
   const raw = target.phone.trim();
   const digits = raw.replace(/[^\d+]/g, '');
   if (digits.startsWith('+')) return { phone: digits };
@@ -61,6 +72,9 @@ export class OtpService {
     // Store under the canonical E.164 key so verify (which normalises the same
     // way) always finds this row regardless of how either side typed the number.
     const target = normalizeOtpTarget(rawTarget);
+    const channel = target.email ? "email" : "sms";
+    const label = this.targetLabel(target);
+    const startedAt = Date.now();
     try {
       // The verification code is generated server-side — never supplied by the
       // caller — so the OTP stays a secret known only to the server and the
@@ -78,6 +92,14 @@ export class OtpService {
         await this.otpRepository.createOtp(target, otp);
       }
 
+      // `rotate` means a code already existed for this target and was replaced —
+      // the previous one is now dead. A user holding a slow-to-arrive SMS and
+      // typing its code will fail against the row; this line is how that shows up
+      // in the log rather than as an unexplained "invalid OTP" report.
+      this.logger.log(
+        `otp.issue channel=${channel} target=${label} action=${existing ? "rotate" : "create"}`,
+      );
+
       // NOTE: do NOT reset the brute-force attempt counter on send. Clearing it
       // here let an attacker wipe the per-target guess budget just by calling
       // /otp/send between guesses. The counter is cleared only when the code is
@@ -86,40 +108,97 @@ export class OtpService {
       // /otp/verify routes (a NestJS ThrottlerGuard / @Throttle) — none exists
       // in the codebase yet.
 
-      if (target.email) {
-        // send email (queued to RabbitMQ via the shared Email service)
-        await this.emailClient.sendEmail({
-          to: target.email,
-          subject: "Your EDR Freight verification code",
-          text: `Your verification code is ${otp}`,
-        });
-      } else {
-        // send sms (queued to RabbitMQ via the shared SMS service)
-        await this.smsClient.sendSms({
-          to: target.phone as string,
-          message: `Your verification code is ${otp}`,
-        });
+      // Both clients report hand-off, not delivery — capture it rather than
+      // discarding it, so "queued=false" is distinguishable from a code that was
+      // published fine and lost downstream at the carrier.
+      const { queued } = target.email
+        ? await this.emailClient.sendEmail({
+            to: target.email,
+            subject: "Your EDR Freight verification code",
+            text: `Your verification code is ${otp}`,
+          })
+        : await this.smsClient.sendSms({
+            to: target.phone as string,
+            message: `Your verification code is ${otp}`,
+          });
+
+      this.logger.log(
+        `otp.dispatch channel=${channel} target=${label} queued=${queued} latencyMs=${
+          Date.now() - startedAt
+        }`,
+      );
+
+      if (!queued) {
+        // The row is committed and we are about to answer "OTP sent successfully",
+        // but nothing left this process. Without this line the only symptom is a
+        // user who never receives a code — indistinguishable from carrier loss,
+        // and the misleading success response makes it look like our side worked.
+        this.logger.error(
+          `otp.dispatch.dropped channel=${channel} target=${label} rabbitmqEnabled=${
+            process.env.RABBITMQ_ENABLED ?? "unset"
+          } — transport reported no hand-off; no code will arrive for this send`,
+        );
       }
 
+      // SECURITY: this logs a live credential in cleartext. Anyone with read
+      // access to the log stream can complete a password reset or a contract
+      // signature for the address on the same line. Kept deliberately (log
+      // aggregation is the debugging path for flaky SMS here) — if that tradeoff
+      // is ever revisited, gate on an env flag rather than deleting the line, so
+      // dev keeps its workflow.
       this.logger.log(`OTP send for ${target.email ?? target.phone}: ${otp}`);
       return {
         success: true,
 
+        // Distinguishes "we published it" from "the transport is a no-op". The
+        // HTTP response shape is unchanged; the controller drops this field.
+        delivered: queued,
+
         message: "OTP sent successfully",
       };
     } catch (error) {
       // Log the real cause (DB/SMS/email failure) with its stack so a deployed
       // "Failed to send OTP" 400 is diagnosable from the API logs, not opaque.
       this.logger.error(
-        `Failed to send OTP to ${target.email ?? target.phone}: ${
-          error instanceof Error ? error.message : String(error)
-        }`,
+        `otp.dispatch.failed channel=${channel} target=${label} latencyMs=${
+          Date.now() - startedAt
+        }: ${error instanceof Error ? error.message : String(error)}`,
         error instanceof Error ? error.stack : undefined,
       );
       throw new BadRequestException("Failed to send OTP");
     }
   }
 
+  /**
+   * Correlation key shared by every `otp.*` line for one address, so a send and
+   * its later verify can be joined with a single grep. The raw target is used
+   * because the code itself is already logged in cleartext above — hashing the
+   * address while printing the credential next to it would buy nothing.
+   */
+  private targetLabel(target: OtpTarget): string {
+    return target.email ?? target.phone ?? "unknown";
+  }
+
+  /**
+   * One line per verify exit path. `result` is a closed set — ok | invalid |
+   * expired | exhausted | not_found — so failures can be counted by reason
+   * instead of inferred from error strings that the frontend also depends on.
+   */
+  private logVerify(
+    target: OtpTarget,
+    mode: "simple" | "action",
+    result: "ok" | "invalid" | "expired" | "exhausted" | "not_found",
+    detail?: string,
+  ) {
+    const line = `otp.verify channel=${
+      target.email ? "email" : "sms"
+    } target=${this.targetLabel(target)} mode=${mode} result=${result}${
+      detail ? ` ${detail}` : ""
+    }`;
+    if (result === "ok") this.logger.log(line);
+    else this.logger.warn(line);
+  }
+
   // ---------------------------------------------------------------------------
   // Verify OTP
   // ---------------------------------------------------------------------------
@@ -134,6 +213,9 @@ export class OtpService {
 
     // not found
     if (!otpData) {
+      // No row for this key. Most often a normalisation mismatch or a code that
+      // was already consumed/burned — not necessarily a caller who never asked.
+      this.logVerify(target, "simple", "not_found");
       throw new BadRequestException(
         target.email ? "Email address not found" : "Phone number not found",
       );
@@ -145,6 +227,12 @@ export class OtpService {
     if (ageMs > this.ACTION_OTP_TTL_MS) {
       await this.otpRepository.deleteOtp(otpData);
       this.actionAttempts.delete(key);
+      this.logVerify(
+        target,
+        "simple",
+        "expired",
+        `ageMs=${ageMs} ttlMs=${this.ACTION_OTP_TTL_MS}`,
+      );
       throw new BadRequestException(
         "Verification code has expired. Request a new one.",
       );
@@ -157,17 +245,30 @@ export class OtpService {
       if (attempts >= this.MAX_ACTION_ATTEMPTS) {
         await this.otpRepository.deleteOtp(otpData);
         this.actionAttempts.delete(key);
+        this.logVerify(
+          target,
+          "simple",
+          "exhausted",
+          `attempts=${attempts}/${this.MAX_ACTION_ATTEMPTS} ageMs=${ageMs}`,
+        );
         throw new BadRequestException(
           "Too many incorrect attempts. Request a new code.",
         );
       }
       this.actionAttempts.set(key, attempts);
+      this.logVerify(
+        target,
+        "simple",
+        "invalid",
+        `attempts=${attempts}/${this.MAX_ACTION_ATTEMPTS} ageMs=${ageMs}`,
+      );
       throw new BadRequestException("Invalid OTP");
     }
 
     // single-use: consume the code on success so it can't be replayed.
     await this.otpRepository.deleteOtp(otpData);
     this.actionAttempts.delete(key);
+    this.logVerify(target, "simple", "ok", `ageMs=${ageMs}`);
 
     return {
       success: true,
@@ -210,6 +311,7 @@ export class OtpService {
     const key = this.targetKey(target);
 
     if (!otpData) {
+      this.logVerify(target, "action", "not_found");
       throw new BadRequestException(
         target.email
           ? "No verification code was requested for this email"
@@ -223,6 +325,7 @@ export class OtpService {
       await this.otpRepository.deleteOtp(otpData);
       this.actionAttempts.delete(key);
 
+      this.logVerify(target, "action", "expired", `ageMs=${ageMs} ttlMs=${ttlMs}`);
       throw new BadRequestException(
         "Verification code has expired. Request a new one.",
       );
@@ -235,18 +338,31 @@ export class OtpService {
         await this.otpRepository.deleteOtp(otpData);
         this.actionAttempts.delete(key);
 
+        this.logVerify(
+          target,
+          "action",
+          "exhausted",
+          `attempts=${attempts}/${this.MAX_ACTION_ATTEMPTS} ageMs=${ageMs}`,
+        );
         throw new BadRequestException(
           "Too many incorrect attempts. Request a new code.",
         );
       }
 
       this.actionAttempts.set(key, attempts);
+      this.logVerify(
+        target,
+        "action",
+        "invalid",
+        `attempts=${attempts}/${this.MAX_ACTION_ATTEMPTS} ageMs=${ageMs}`,
+      );
       throw new BadRequestException("Invalid verification code");
     }
 
     // single-use: consume on success
     await this.otpRepository.deleteOtp(otpData);
     this.actionAttempts.delete(key);
+    this.logVerify(target, "action", "ok", `ageMs=${ageMs}`);
 
     return { success: true };
   }
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx b/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
index 27e51b403..47c00bef2 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
@@ -4,6 +4,7 @@ import {
   Divider,
   Group,
   Loader,
+  Select,
   SimpleGrid,
   Stack,
   Text,
@@ -13,12 +14,13 @@ import { zodResolver } from "@hookform/resolvers/zod";
 import { useQuery } from "@tanstack/react-query";
 import { AlertCircle, ArrowLeft, ArrowRight } from "lucide-react";
 import { useEffect, useMemo, useRef, useState } from "react";
-import { useForm } from "react-hook-form";
+import { Controller, useForm } from "react-hook-form";
 
 import type { AuthUser } from "@/types/auth";
 import type { CreateCompanyPayload } from "@/services/companies.service";
 import type { ProfileResponse, UpdateProfilePayload } from "@/types/profile";
 import type { CompanyRegistrationData } from "@edr/types";
+import { ETHIOPIAN_REGIONS } from "@edr/types";
 import { ControlledPhoneField, toEthiopianE164 } from "@/components/PhoneField";
 import { SmartFileInput } from "@edr/ui-common";
 import { getMinFiles } from "@/types/fileUploadSettings";
@@ -675,12 +677,24 @@ export default function CompanyProfileForm({
                 Address Information
               </Text>
               <SimpleGrid cols={2} spacing="md">
-                <TextInput
-                  label="Region"
-                  placeholder="Tigray"
-                  required
-                  error={errors.region?.message}
-                  {...register("region")}
+                <Controller
+                  name="region"
+                  control={control}
+                  render={({ field }) => (
+                    <Select
+                      label="Region"
+                      placeholder="Select region"
+                      required
+                      searchable
+                      data={ETHIOPIAN_REGIONS.map((r) => ({ value: r, label: r }))}
+                      error={errors.region?.message}
+                      // "" (unresolved eTrade value, or a legacy row whose
+                      // region isn't in the list) must read as "nothing picked".
+                      value={field.value || null}
+                      onChange={(v) => field.onChange(v ?? "")}
+                      onBlur={field.onBlur}
+                    />
+                  )}
                 />
                 <TextInput
                   label="Zone"
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts
index 44c2cdec1..f84783607 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts
@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ETHIOPIAN_REGIONS } from "@edr/types";
 
 import { isValidPhone } from "@/components/PhoneField";
 
@@ -35,7 +36,9 @@ export const onboardingSchema = z.object({
   renewedTo: z.string().optional(),
   // Address fields are user-entered and required (the registration/license
   // fields above are read-only confirmations pulled from eTrade).
-  region: z.string().min(1, "Region is required"),
+  // Region is a closed set; zone/woreda/kebele stay free text until the platform
+  // has an authoritative dataset of Ethiopian zones/woredas/kebeles.
+  region: z.enum(ETHIOPIAN_REGIONS, { message: "Region is required" }),
   zone: z.string().min(1, "Zone is required"),
   woreda: z.string().min(1, "Woreda is required"),
   kebele: z.string().min(1, "Kebele is required"),
diff --git a/packages/types/src/freight/ethiopian-regions.catalog.ts b/packages/types/src/freight/ethiopian-regions.catalog.ts
new file mode 100644
index 000000000..93a574b36
--- /dev/null
+++ b/packages/types/src/freight/ethiopian-regions.catalog.ts
@@ -0,0 +1,97 @@
+/**
+ * Ethiopia's first-level administrative divisions: regional states plus the two
+ * chartered city administrations.
+ *
+ * NOTE — this list churned recently and should be re-confirmed with EDR before
+ * being treated as final. SNNPR was progressively dissolved: Sidama split off in
+ * 2020, South West Ethiopia Peoples' in 2021, and the remainder became Central
+ * Ethiopia and South Ethiopia in 2023. Records created before those splits may
+ * still carry "SNNPR" or "Southern Nations".
+ */
+export const ETHIOPIAN_REGIONS = [
+  "Addis Ababa",
+  "Afar",
+  "Amhara",
+  "Benishangul-Gumuz",
+  "Central Ethiopia",
+  "Dire Dawa",
+  "Gambela",
+  "Harari",
+  "Oromia",
+  "Sidama",
+  "Somali",
+  "South Ethiopia",
+  "South West Ethiopia Peoples'",
+  "Tigray",
+] as const;
+
+export type EthiopianRegion = (typeof ETHIOPIAN_REGIONS)[number];
+
+/**
+ * Free-text region values seen in the wild — eTrade returns uncoded uppercase
+ * strings, and pre-dropdown rows were hand-typed. Keys are lowercased and
+ * whitespace-collapsed before lookup, so only spelling/naming variants belong
+ * here, not case variants.
+ */
+const REGION_ALIASES: Record<string, EthiopianRegion> = {
+  // Spelling and transliteration variants.
+  oromoia: "Oromia",
+  oromiya: "Oromia",
+  oromina: "Oromia",
+  addisabeba: "Addis Ababa",
+  "addis abeba": "Addis Ababa",
+  "dire dawa city": "Dire Dawa",
+  "benishangul gumuz": "Benishangul-Gumuz",
+  "benshangul-gumuz": "Benishangul-Gumuz",
+  "beneshangul-gumuz": "Benishangul-Gumuz",
+  gambella: "Gambela",
+  tigrai: "Tigray",
+  tigre: "Tigray",
+  "south west ethiopia": "South West Ethiopia Peoples'",
+  "south west ethiopia peoples": "South West Ethiopia Peoples'",
+  "southwest ethiopia": "South West Ethiopia Peoples'",
+
+  // eTrade frequently returns a ZONE in the Region slot. These map the zone back
+  // to its parent region; the zone itself is preserved in the `zone` field.
+  "eastern tigray": "Tigray",
+  "western tigray": "Tigray",
+  "southern tigray": "Tigray",
+  "central tigray": "Tigray",
+  "north wollo": "Amhara",
+  "south wollo": "Amhara",
+  "east gojjam": "Amhara",
+  "west gojjam": "Amhara",
+  "north shewa": "Amhara",
+  "east shewa": "Oromia",
+  "west shewa": "Oromia",
+  "arsi": "Oromia",
+  "bale": "Oromia",
+  "borena": "Oromia",
+  "jimma": "Oromia",
+  "gamo": "South Ethiopia",
+  "gofa": "South Ethiopia",
+  "wolayita": "South Ethiopia",
+};
+
+/** Collapse whitespace and case so lookups are tolerant of formatting noise. */
+function canonicalKey(value: string): string {
+  return value.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+/**
+ * Map an arbitrary region string (eTrade payload, legacy row, hand entry) onto a
+ * canonical region. Returns `null` when it cannot be resolved — callers should
+ * leave the field empty and let the user pick, rather than persisting a guess.
+ */
+export function normalizeRegion(
+  value: string | null | undefined,
+): EthiopianRegion | null {
+  if (!value) return null;
+  const key = canonicalKey(value);
+  if (!key) return null;
+
+  const exact = ETHIOPIAN_REGIONS.find((r) => canonicalKey(r) === key);
+  if (exact) return exact;
+
+  return REGION_ALIASES[key] ?? null;
+}
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index 1dabbca19..be13ed349 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -7,6 +7,7 @@ export * from "./overview";
 export * from "./etrade";
 export * from "./contracts";
 export * from "./clearance-files.catalog";
+export * from "./ethiopian-regions.catalog";
 export * from "./notifications";
 export * from "./booking-window-ws";
 export * from "./support-chat";

From b67aa813f986bd320886b3ccd3a78b9a4f1b7eae Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 20 Jul 2026 08:25:54 +0000
Subject: [PATCH 12/15] fix: type error in portal

---
 .../src/pages/accounts/companyProfileForm/schema.ts   | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts
index f84783607..275b8a4fa 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts
@@ -38,7 +38,16 @@ export const onboardingSchema = z.object({
   // fields above are read-only confirmations pulled from eTrade).
   // Region is a closed set; zone/woreda/kebele stay free text until the platform
   // has an authoritative dataset of Ethiopian zones/woredas/kebeles.
-  region: z.enum(ETHIOPIAN_REGIONS, { message: "Region is required" }),
+  //
+  // Deliberately `.refine` over `z.enum`: the form needs "" as its unselected
+  // sentinel (default value, and legacy rows whose region isn't in the list). A
+  // literal union makes "" untypable, which also splits the resolver's
+  // input/output types and breaks useForm's inference for every other field.
+  region: z
+    .string()
+    .refine((v) => (ETHIOPIAN_REGIONS as readonly string[]).includes(v), {
+      message: "Region is required",
+    }),
   zone: z.string().min(1, "Zone is required"),
   woreda: z.string().min(1, "Woreda is required"),
   kebele: z.string().min(1, "Kebele is required"),

From 0727de0f4dc12d7d87f58a6d2b818b8e2e1b6644 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 20 Jul 2026 07:46:38 +0000
Subject: [PATCH 13/15] Refactor clearance terminology to document approval
 across services and UI components

---
 .../booking-lifecycle-notifier.service.ts     |  8 +++----
 .../contracts/contract-clearance.service.ts   |  2 +-
 .../detail/ClearanceReviewSection.tsx         | 10 +++++----
 .../ContractClearanceReviewSection.tsx        |  6 +++---
 .../trainBuilder/BuildTrainModal.tsx          |  3 ++-
 .../trainBuilder/EditTrainDetailsModal.tsx    |  3 ++-
 .../src/hooks/contracts/useContracts.ts       |  8 ++++---
 .../src/hooks/useImportTrainNumberOptions.ts  | 21 ++++++++++++-------
 .../bookings/DocumentClearanceListPage.tsx    |  2 +-
 .../contracts/ContractClearanceListPage.tsx   |  4 ++--
 10 files changed, 40 insertions(+), 27 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.ts
index 1cef9528c..3809dc086 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.ts
@@ -157,13 +157,13 @@ export class BookingLifecycleNotifierService {
     });
   }
 
-  /** Clearance finalized → customer can proceed to request operation. */
+  /** Document approval finalized → customer can proceed to request operation. */
   clearanceReady(b: Booking): void {
     const msg =
-      `Clearance for booking ${b.reference} is complete. ` +
+      `Document approval for booking ${b.reference} is finalized. ` +
       `You can now proceed to request operation from the portal.`;
-    void this.notifyContact(b, msg, 'CLEARANCE READY');
-    this.inApp(b, 'Clearance complete', msg, {
+    void this.notifyContact(b, msg, 'DOCUMENT APPROVAL FINALIZED');
+    this.inApp(b, 'Document approval finalized', msg, {
       type: NotificationType.CLEARANCE_DECISION,
     });
   }
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts
index d752d071a..029952f45 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts
@@ -456,7 +456,7 @@ export class ContractClearanceService {
     const allowed = ['CLEARANCE_UNDER_REVIEW', 'AWAITING_CLEARANCE_DOCUMENTS'];
     if (!allowed.includes(contract.status)) {
       throw new ConflictException(
-        `Cannot finalize clearance on status "${contract.status}".`,
+        `Cannot finalize document approval on status "${contract.status}".`,
       );
     }
   }
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/ClearanceReviewSection.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/ClearanceReviewSection.tsx
index 3dcf1ea9e..501e074e2 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/ClearanceReviewSection.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/ClearanceReviewSection.tsx
@@ -135,12 +135,14 @@ export function ClearanceReviewSection({
   const finalizeMutation = useMutation({
     mutationFn: () => bookingsService.finalizeClearance(bookingId),
     onSuccess: () => {
-      toast.success("Clearance finalized");
+      toast.success("Document approval finalized");
       refresh();
     },
     onError: (e) =>
       toast.error(
-        e instanceof Error ? e.message : "Could not finalize clearance",
+        e instanceof Error
+          ? e.message
+          : "Could not finalize document approval",
       ),
   });
 
@@ -366,7 +368,7 @@ export function ClearanceReviewSection({
         <Alert color="red" radius="md" icon={<AlertCircle size={16} />}>
           {finalizeMutation.error instanceof Error
             ? finalizeMutation.error.message
-            : "Could not finalize clearance."}
+            : "Could not finalize document approval."}
         </Alert>
       )}
 
@@ -445,7 +447,7 @@ export function ClearanceReviewSection({
               loading={finalizeMutation.isPending}
               onClick={() => finalizeMutation.mutate()}
             >
-              Finalize clearance
+              Finalize document approval
             </Button>
           </Group>
         </Paper>
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/ContractClearanceReviewSection.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/ContractClearanceReviewSection.tsx
index c85dc0b07..c7d668ade 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/ContractClearanceReviewSection.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/ContractClearanceReviewSection.tsx
@@ -68,7 +68,7 @@ export interface ContractClearanceReviewSectionProps {
   queriesLocked?: boolean;
   /**
    * ONE_TIME customs contracts use the phased milestone workflow. Hides the
-   * legacy "Finalize clearance" shortcut; booking readiness follows delivery
+   * legacy "Finalize document approval" shortcut; booking readiness follows delivery
    * order (import) or export release.
    */
   phasedCustoms?: boolean;
@@ -393,7 +393,7 @@ export function ContractClearanceReviewSection({
         <Alert color="red" radius="md" icon={<AlertCircle size={16} />}>
           {finalizeClearance.error instanceof Error
             ? finalizeClearance.error.message
-            : "Could not finalize clearance."}
+            : "Could not finalize document approval."}
         </Alert>
       )}
 
@@ -482,7 +482,7 @@ export function ContractClearanceReviewSection({
                 })
               }
             >
-              Finalize clearance
+              Finalize document approval
             </Button>
           </Group>
         </Paper>
diff --git a/apps/edr-freight-web/backoffice/src/components/trainBuilder/BuildTrainModal.tsx b/apps/edr-freight-web/backoffice/src/components/trainBuilder/BuildTrainModal.tsx
index 05b4bd546..925ff528d 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainBuilder/BuildTrainModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainBuilder/BuildTrainModal.tsx
@@ -160,7 +160,8 @@ export default function BuildTrainModal({ opened, onClose, onBuilt }: BuildTrain
             onChange={(value) => setImportTrainNumber(value ?? "")}
             searchable
             clearable
-            nothingFoundMessage="No free run numbers — add more in Dropdown Settings"
+            nothingFoundMessage={importNumbers.emptyMessage}
+            error={importNumbers.settingMissing ? importNumbers.emptyMessage : undefined}
           />
         </Group>
         <Select
diff --git a/apps/edr-freight-web/backoffice/src/components/trainBuilder/EditTrainDetailsModal.tsx b/apps/edr-freight-web/backoffice/src/components/trainBuilder/EditTrainDetailsModal.tsx
index 8eb64d3ef..cd65a568a 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainBuilder/EditTrainDetailsModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainBuilder/EditTrainDetailsModal.tsx
@@ -105,7 +105,8 @@ const EditTrainDetailsModal = ({ train, onClose }: EditTrainDetailsModalProps) =
             }}
             searchable
             clearable
-            nothingFoundMessage="No free run numbers — add more in Dropdown Settings"
+            nothingFoundMessage={importNumbers.emptyMessage}
+            error={importNumbers.settingMissing ? importNumbers.emptyMessage : undefined}
             radius="md"
           />
           <TextInput
diff --git a/apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts b/apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts
index 572ad6f8e..306d92536 100644
--- a/apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts
+++ b/apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts
@@ -348,14 +348,16 @@ export function useContractClearanceMutations(
     onSuccess: () => {
       toast.success(
         selfClear
-          ? "Clearance approved — customer can now book"
-          : "Clearance finalized — ready for booking",
+          ? "Document approval finalized — customer can now book"
+          : "Document approval finalized — ready for booking",
       );
       refresh();
     },
     onError: (e) =>
       toast.error(
-        e instanceof Error ? e.message : "Could not finalize clearance",
+        e instanceof Error
+          ? e.message
+          : "Could not finalize document approval",
       ),
   });
 
diff --git a/apps/edr-freight-web/backoffice/src/hooks/useImportTrainNumberOptions.ts b/apps/edr-freight-web/backoffice/src/hooks/useImportTrainNumberOptions.ts
index a26e127f3..d2cf2710d 100644
--- a/apps/edr-freight-web/backoffice/src/hooks/useImportTrainNumberOptions.ts
+++ b/apps/edr-freight-web/backoffice/src/hooks/useImportTrainNumberOptions.ts
@@ -1,7 +1,6 @@
 import { useQuery } from "@tanstack/react-query";
 import { useMemo } from "react";
 
-import { IMPORT_TRAIN_OPTIONS } from "@/constants/trainRuns";
 import { api } from "@/services/api";
 
 /** Dropdown-settings code holding the admin-managed IMPORT run numbers. */
@@ -14,10 +13,11 @@ export interface ImportTrainNumberOption {
 }
 
 /**
- * Selectable IMPORT run numbers for the Train Builder, sourced from the
- * admin-managed `import_train_numbers` dropdown setting (admins add new runs
- * from the Dropdown Settings editor). Falls back to the legacy hardcoded run
- * list while the setting is missing or has no options.
+ * Selectable IMPORT run numbers for the Train Builder, sourced solely from the
+ * admin-managed `import_train_numbers` dropdown setting — admins add and remove
+ * runs from /dashboard/dropdown-settings and the pickers follow. There is no
+ * hardcoded fallback on purpose: a missing setting must be visible (see
+ * `settingMissing`) rather than masked by stale defaults.
  *
  * Numbers already claimed by an existing train are kept in the list but
  * disabled and tagged "in use". Pass `currentNumber` when editing a train so
@@ -37,14 +37,13 @@ export function useImportTrainNumberOptions(currentNumber?: string | null) {
   );
 
   const options = useMemo<ImportTrainNumberOption[]>(() => {
-    const configured = [...(settingQuery.data?.children ?? [])]
+    const base = [...(settingQuery.data?.children ?? [])]
       .filter((option) => !option.disabled)
       .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
       .map((option) => ({
         value: option.value,
         label: option.label || option.value,
       }));
-    const base = configured.length ? configured : IMPORT_TRAIN_OPTIONS;
 
     const used = new Set(usedQuery.data?.importTrainNumbers ?? []);
     if (currentNumber) used.delete(currentNumber);
@@ -60,8 +59,16 @@ export function useImportTrainNumberOptions(currentNumber?: string | null) {
     return items;
   }, [settingQuery.data, usedQuery.data, currentNumber]);
 
+  const settingMissing = settingQuery.isError;
+
   return {
     options,
     isLoading: settingQuery.isLoading || usedQuery.isLoading,
+    /** True when the dropdown setting is absent — surfaced instead of silently
+     * falling back, so a broken config is visible rather than looking normal. */
+    settingMissing,
+    emptyMessage: settingMissing
+      ? `Dropdown setting "${IMPORT_TRAIN_NUMBERS_CODE}" is missing — create it in Dropdown Settings`
+      : "No free run numbers — add more in Dropdown Settings",
   };
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceListPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceListPage.tsx
index 542852a5f..34e659177 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceListPage.tsx
@@ -325,7 +325,7 @@ export default function DocumentClearanceListPage({
           subtitle={
             opsMode
               ? "Review the customer's own clearance documents per shipment booking, raise queries, and finalize."
-              : "Review customer documents, raise queries, and finalize clearance for each booking."
+              : "Review customer documents, raise queries, and finalize document approval for each booking."
           }
           meta={statusBadge}
           action={
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx
index 9cc9919e3..328736f3d 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx
@@ -256,7 +256,7 @@ function StatusBadge({ row }: { row: ClearanceRow }) {
   if (row.ready) {
     return (
       <Tooltip
-        label="Clearance finalized — the customer creates the booking in the portal"
+        label="Document approval finalized — the customer creates the booking in the portal"
         withArrow
       >
         <Badge
@@ -266,7 +266,7 @@ function StatusBadge({ row }: { row: ClearanceRow }) {
           radius="sm"
           leftSection={<PackageCheck size={12} />}
         >
-          Clearance finalized
+          Documents approved
         </Badge>
       </Tooltip>
     );

From 540f4a1ff666badc5393bd4868d2a6792faa65ee Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 20 Jul 2026 10:52:20 +0000
Subject: [PATCH 14/15] changes

---
 .../modules/contracts/contracts.service.ts    | 13 ++++--------
 .../train-scheduling/booking-batch.service.ts | 17 +++++++++-------
 .../train-scheduling.service.ts               | 14 +++++++++++--
 .../TrainScheduleV2ListPage.tsx               |  6 ++++--
 .../components/DocumentsTab.tsx               | 20 +++++++++++++++++--
 .../pages/bookings/resubmit/resubmitDocs.ts   |  8 ++++++++
 .../pages/contracts/ContractDetailPage.tsx    |  9 ++++++++-
 7 files changed, 64 insertions(+), 23 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/contracts/contracts.service.ts b/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
index 224745cc4..c98e24b19 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
@@ -374,23 +374,18 @@ export class ContractsService {
     if (companyProfileId) {
       // Business-license files are FileRecords (resource "company_profiles");
       // carry the live ones by reference. Staged/pending uploads are excluded by
-      // code. Codes are slugged from each document name so they group under
-      // "Profile documents" on the contract detail page.
+      // code. The `business_license` prefix is preserved so the portal groups
+      // them under "Business license" instead of the clearance catch-all — the
+      // index suffix keeps multiple licences distinct.
       const records = await this.filesService.findByResource(
         companyProfileId,
         'company_profiles',
       );
-      const slug = (name: string) =>
-        name
-          .toLowerCase()
-          .replace(/\.[a-z0-9]+$/, '')
-          .replace(/[^a-z0-9]+/g, '_')
-          .replace(/^_+|_+$/g, '') || 'profile_document';
 
       records
         .filter((r) => r.code === 'business_license')
         .forEach((r, i) => {
-          const code = `${slug(r.name)}_${i + 1}`;
+          const code = `business_license_${i + 1}`;
           if (existingCodes.has(code)) return;
           docs.push({
             code,
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts
index 4a836060e..415b5df97 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts
@@ -3444,19 +3444,22 @@ export class BookingBatchService implements OnModuleInit {
 
   /**
    * Physical wagons marshalled in the schedule's built train, or null when the
-   * schedule has no built train (or the consist is still empty) and the legacy
-   * locomotive-derived capacity must apply. This count is what caps a built
-   * train's bookings: 50 wagons coupled → 50 wagon slots, no more.
+   * schedule has NO built train and the legacy locomotive-derived capacity must
+   * apply. This count is what caps a built train's bookings: 50 wagons coupled
+   * → 50 wagon slots, no more.
+   *
+   * A built train with an EMPTY consist returns 0, NOT null: zero coupled
+   * wagons means zero capacity. Folding that case into null used to hand an
+   * un-consisted train the abstract locomotive budget, so an empty train
+   * advertised its full maxWagons as free space and accepted bookings the
+   * allocator could never place.
    */
   private async builtTrainWagonCount(
     schedule: TrainSchedule,
   ): Promise<number | null> {
     const trainId = schedule.trainSet?.train?.id;
     if (!trainId) return null;
-    const count = await this.dataSource
-      .getRepository(Wagon)
-      .count({ where: { trainId } });
-    return count > 0 ? count : null;
+    return this.dataSource.getRepository(Wagon).count({ where: { trainId } });
   }
 
   /**
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.service.ts
index 9d426077e..2f7ca0776 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.service.ts
@@ -7131,9 +7131,19 @@ export class TrainSchedulingService {
 
     await this.dataSource.transaction(async (manager) => {
       await manager.getRepository(TrainSetWagon).delete(trainSetWagonId);
+      // Recount from the slot rows rather than decrementing the cached counter.
+      // A blind `wagonCount - 1` desyncs the moment two removals race or the
+      // in-memory schedule graph is stale, and the counter is what the schedule
+      // capacity math reads.
+      const remaining = await manager.getRepository(TrainSetWagon).find({
+        where: { trainSetId: schedule.trainSetId },
+        select: { id: true, lengthMeters: true },
+      });
       await manager.getRepository(TrainSet).update(schedule.trainSetId, {
-        wagonCount: Math.max(0, (schedule.trainSet?.wagonCount ?? 0) - 1),
-        totalLengthMeters: Math.max(0, (schedule.trainSet?.totalLengthMeters ?? 0) - (wagon.lengthMeters ?? 0)),
+        wagonCount: remaining.length,
+        totalLengthMeters: roundTons(
+          remaining.reduce((sum, w) => sum + (Number(w.lengthMeters) || 0), 0),
+        ),
       });
     });
 
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
index f40bd9526..aae182103 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
@@ -400,7 +400,9 @@ export default function TrainScheduleV2ListPage() {
         cell: ({ row }) => (
           <Group gap={6} wrap="nowrap">
             <MetricChip value={row.original.bookingsCount} label="bkg" />
-            <MetricChip value={row.original.wagonCount} label="wgn" />
+            {/* Wagon SLOTS this schedule's bookings occupy — not the coupled
+                consist. A built train shows 0 here until bookings are allocated. */}
+            <MetricChip value={row.original.wagonCount} label="wgn used" />
             <MetricChip value={`${row.original.totalWeightTons}T`} label="" subtle />
           </Group>
         ),
@@ -950,7 +952,7 @@ function ScheduleCard({
           </Group>
           <Group gap={6} wrap="nowrap">
             <MetricChip value={schedule.bookingsCount} label="bkg" />
-            <MetricChip value={schedule.wagonCount} label="wgn" />
+            <MetricChip value={schedule.wagonCount} label="wgn used" />
             <MetricChip value={`${schedule.totalWeightTons}T`} label="" subtle />
           </Group>
         </Group>
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/DocumentsTab.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/DocumentsTab.tsx
index 983411e89..8934a0a60 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/DocumentsTab.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/DocumentsTab.tsx
@@ -158,7 +158,14 @@ const BUSINESS_LICENSE_DOC_CODES = new Set([
   "business_license",
   "commercial_license",
   "investment_license",
+  "trade_license",
 ]);
+
+// Licences carried from the company profile are suffixed per file
+// (`business_license_1`), so match on the stripped base code too.
+const isBusinessLicenseCode = (code: string): boolean =>
+  BUSINESS_LICENSE_DOC_CODES.has(code) ||
+  BUSINESS_LICENSE_DOC_CODES.has(code.replace(/_\d+$/, ""));
 const PROFILE_DOC_CODES = new Set([
   "tin_certificate",
   "national_id",
@@ -183,6 +190,15 @@ const KNOWN_FILE_LABELS: Record<string, string> = {
 
 function fileLabel(f: AnyFile) {
   if (KNOWN_FILE_LABELS[f.code]) return KNOWN_FILE_LABELS[f.code];
+  // Profile documents carried onto the contract are suffixed per file
+  // (`business_license_2`) — label them from the base code, numbered.
+  const base = f.code.replace(/_\d+$/, "");
+  if (KNOWN_FILE_LABELS[base]) {
+    const n = f.code.slice(base.length + 1);
+    return n && n !== "1"
+      ? `${KNOWN_FILE_LABELS[base]} ${n}`
+      : KNOWN_FILE_LABELS[base];
+  }
   // Ad-hoc uploads carry a generated code (custom_<ts>_<i>) — use the filename.
   if (f.code.startsWith("custom_")) return f.name;
   return f.code
@@ -245,7 +261,7 @@ export function DocumentsTab({ booking }: { booking: Freight.IBooking }) {
   const contractFiles = (contract?.files ?? []) as AnyFile[];
   const contractPdf = contractFiles.find((f) => f.code === "contract");
   const licenseFiles = contractFiles.filter((f) =>
-    BUSINESS_LICENSE_DOC_CODES.has(f.code),
+    isBusinessLicenseCode(f.code),
   );
   const profileFiles = contractFiles.filter((f) => PROFILE_DOC_CODES.has(f.code));
 
@@ -428,7 +444,7 @@ export function DocumentsTab({ booking }: { booking: Freight.IBooking }) {
                   title={fileLabel(f)}
                   meta={
                     PROFILE_DOC_CODES.has(f.code) ||
-                    BUSINESS_LICENSE_DOC_CODES.has(f.code)
+                    isBusinessLicenseCode(f.code)
                       ? "From your company profile"
                       : f.name
                   }
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/resubmit/resubmitDocs.ts b/apps/edr-freight-web/portal/src/pages/bookings/resubmit/resubmitDocs.ts
index 0a2f1a30f..fb36c3fd2 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/resubmit/resubmitDocs.ts
+++ b/apps/edr-freight-web/portal/src/pages/bookings/resubmit/resubmitDocs.ts
@@ -26,6 +26,14 @@ const LABEL_BY_CODE = new Map<string, string>([
 export function labelForDocCode(code: string): string {
   const known = LABEL_BY_CODE.get(code);
   if (known) return known;
+  // Profile documents carried onto a contract are suffixed per file
+  // ("business_license_2") — label from the base code, numbered past the first.
+  const base = code.replace(/_\d+$/, "");
+  const baseLabel = LABEL_BY_CODE.get(base);
+  if (baseLabel) {
+    const n = code.slice(base.length + 1);
+    return n && n !== "1" ? `${baseLabel} ${n}` : baseLabel;
+  }
   return code
     .replace(/^custom_\d+_\d+$/, "Additional document")
     .replace(/[_-]+/g, " ")
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/ContractDetailPage.tsx b/apps/edr-freight-web/portal/src/pages/contracts/ContractDetailPage.tsx
index f03f99b01..89870ee93 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/ContractDetailPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/ContractDetailPage.tsx
@@ -134,8 +134,15 @@ const BUSINESS_LICENSE_DOC_CODES = new Set([
   "business_license",
   "commercial_license",
   "investment_license",
+  "trade_license",
 ]);
 
+// Licences carried from the company profile are suffixed per file
+// (`business_license_1`), so match on the stripped base code too.
+const isBusinessLicenseCode = (code: string): boolean =>
+  BUSINESS_LICENSE_DOC_CODES.has(code) ||
+  BUSINESS_LICENSE_DOC_CODES.has(code.replace(/_\d+$/, ""));
+
 // Onboarding / company-profile document codes seeded in file-upload-settings.
 // These get attached to the contract at creation and belong under "Profile
 // documents" rather than the clearance set.
@@ -196,7 +203,7 @@ function groupContractDocuments(
     // The generated contract PDF lives in the contract list / home rows, not
     // here. Signature images are baked into that PDF — skip both.
     if (f.code === "contract" || f.code.startsWith("signature_")) continue;
-    else if (BUSINESS_LICENSE_DOC_CODES.has(f.code)) businessLicense.push(f);
+    else if (isBusinessLicenseCode(f.code)) businessLicense.push(f);
     else if (PROFILE_DOC_CODES.has(f.code)) profile.push(f);
     else if (includeClearance && isClearanceCode(f.code)) clearance.push(f);
     else other.push(f);

From c8a70593cf2b76bef49a0d1e0bc404d31a380a96 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 20 Jul 2026 11:28:31 +0000
Subject: [PATCH 15/15] fix(mile): apply one truck-load rule to customer and
 EDR haulage alike
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A truck holds one 40ft or two 20ft, a container booking takes no more trucks
than it has containers, and a bulk booking takes trucks until its tonnage is
hauled away. The same physics whoever drives, but the rule was written out
four times — addTruck, updateTruck, departTruck and LastMileService — beside
a byte-identical container-size query. Copies drift: that is how the
self-haul guard ended up enforced on one side only.

The bulk cap was the real gap. EDR summed net_weight_tons of departed trucks
and refused another once the booking was drawn down. The customer side had
no cap at all: for bulk it skipped straight past every check, so a self-haul
bulk booking could take unlimited trucks.

It could not simply reuse the EDR sum. customer_truck_assignments had no net
and no tare, only a gross_weight_kg that holds tonnes despite its name and
that nothing in the live flow ever wrote — release() recorded exit weights
against the EDR table alone, which is why all five customer trucks on dev
have neither weight nor departure. Any drawdown keyed on it would have
summed zero forever and never fired.

So the customer table now carries tare_weight_tons and net_weight_tons to
match the EDR one, release() records the customer truck's exit as it already
did for EDR, and the drawdown counts both sources — a booking hauls by one
path or the other and "until no tonnage is left" means the same either way.

Also locks a load once its truck has arrived on the EDR side, which the
customer side has always done, and fills the arrival form from the customer
truck on file: the prefill read booking.customer_truck_*, which multi-truck
self-haul leaves null, so a booking with a truck assigned opened blank.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../src/common/truck-load.util.spec.ts        | 159 ++++++++++++++++++
 .../src/common/truck-load.util.ts             | 148 ++++++++++++++++
 ...00000000000-AddCustomerTruckExitWeights.ts |  46 +++++
 .../bookings/customer-truck.service.ts        | 117 ++++---------
 .../customer-truck-assignment.entity.ts       |  12 ++
 .../modules/last-mile/last-mile.service.ts    | 108 +++++-------
 .../warehouses/warehouse-inventory.service.ts |  25 +++
 .../warehouses/ReleaseOrderModal.tsx          |  18 ++
 8 files changed, 487 insertions(+), 146 deletions(-)
 create mode 100644 apps/edr-freight-api/src/common/truck-load.util.spec.ts
 create mode 100644 apps/edr-freight-api/src/common/truck-load.util.ts
 create mode 100644 apps/edr-freight-api/src/migrations/2400000000000-AddCustomerTruckExitWeights.ts

diff --git a/apps/edr-freight-api/src/common/truck-load.util.spec.ts b/apps/edr-freight-api/src/common/truck-load.util.spec.ts
new file mode 100644
index 000000000..fbb3a436a
--- /dev/null
+++ b/apps/edr-freight-api/src/common/truck-load.util.spec.ts
@@ -0,0 +1,159 @@
+import { BadRequestException, ConflictException } from '@nestjs/common';
+
+import {
+  assertBulkTonnageRemains,
+  assertTruckCountWithinContainers,
+  assertTruckLoad,
+  remainingBulkTons,
+} from './truck-load.util';
+
+/**
+ * One physical rule, shared by customer self-haul and EDR last-mile. It used to
+ * be written out three times (addTruck, updateTruck, departTruck) plus a fourth
+ * in LastMileService.
+ */
+describe('assertTruckLoad', () => {
+  const booking = ['ABCD1234567', 'ABCD7654321', 'WXYZ1111111'];
+
+  it('accepts two 20ft containers on one truck', () => {
+    expect(() =>
+      assertTruckLoad({
+        containers: ['ABCD1234567', 'ABCD7654321'],
+        bookingContainers: booking,
+        sizes: ['20ft', '20ft'],
+      }),
+    ).not.toThrow();
+  });
+
+  it('accepts a single 40ft container', () => {
+    expect(() =>
+      assertTruckLoad({
+        containers: ['ABCD1234567'],
+        bookingContainers: booking,
+        sizes: ['40ft'],
+      }),
+    ).not.toThrow();
+  });
+
+  it('rejects a 40ft sharing the truck — it fills the bed', () => {
+    expect(() =>
+      assertTruckLoad({
+        containers: ['ABCD1234567', 'ABCD7654321'],
+        bookingContainers: booking,
+        sizes: ['40ft', '20ft'],
+      }),
+    ).toThrow(BadRequestException);
+  });
+
+  it('rejects more than two containers', () => {
+    expect(() =>
+      assertTruckLoad({
+        containers: ['ABCD1234567', 'ABCD7654321', 'WXYZ1111111'],
+        bookingContainers: booking,
+        sizes: ['20ft', '20ft', '20ft'],
+      }),
+    ).toThrow(BadRequestException);
+  });
+
+  it('rejects a container that is not on the booking', () => {
+    expect(() =>
+      assertTruckLoad({
+        containers: ['ZZZZ9999999'],
+        bookingContainers: booking,
+        sizes: ['20ft'],
+      }),
+    ).toThrow(BadRequestException);
+  });
+
+  it('rejects a container already riding another truck', () => {
+    expect(() =>
+      assertTruckLoad({
+        containers: ['ABCD1234567'],
+        bookingContainers: booking,
+        sizes: ['20ft'],
+        assignedElsewhere: ['ABCD1234567'],
+      }),
+    ).toThrow(ConflictException);
+  });
+
+  it('skips membership checks when the booking has no containers (bulk)', () => {
+    expect(() =>
+      assertTruckLoad({ containers: [], bookingContainers: [], sizes: [] }),
+    ).not.toThrow();
+  });
+
+  it('still caps the count when the booking has no containers', () => {
+    expect(() =>
+      assertTruckLoad({
+        containers: ['A', 'B', 'C'],
+        bookingContainers: [],
+        sizes: [],
+      }),
+    ).toThrow(BadRequestException);
+  });
+});
+
+describe('assertBulkTonnageRemains', () => {
+  it('allows another truck while tonnage is left', () => {
+    expect(() => assertBulkTonnageRemains(100, 40)).not.toThrow();
+  });
+
+  it('rejects a truck once the booking is fully hauled', () => {
+    expect(() => assertBulkTonnageRemains(100, 0)).toThrow(BadRequestException);
+  });
+
+  it('does not cap a booking with no declared weight', () => {
+    // Nothing to draw down against — capping here would block every truck.
+    expect(() => assertBulkTonnageRemains(0, 0)).not.toThrow();
+  });
+});
+
+describe('remainingBulkTons', () => {
+  const dataSourceReturning = (totalTons: string, hauledTons: string) =>
+    ({ query: jest.fn().mockResolvedValue([{ totalTons, hauledTons }]) }) as never;
+
+  it('counts trucks from both haulage paths against the declared weight', async () => {
+    const result = await remainingBulkTons(dataSourceReturning('100', '60'), 'b-1');
+
+    expect(result).toEqual({
+      totalTons: 100,
+      hauledTons: 60,
+      remainingTons: 40,
+      complete: false,
+    });
+  });
+
+  it('is complete once everything is hauled', async () => {
+    const result = await remainingBulkTons(dataSourceReturning('100', '100'), 'b-1');
+
+    expect(result.remainingTons).toBe(0);
+    expect(result.complete).toBe(true);
+  });
+
+  it('never reports negative tonnage when trucks overshoot', async () => {
+    const result = await remainingBulkTons(dataSourceReturning('100', '104'), 'b-1');
+
+    expect(result.remainingTons).toBe(0);
+    expect(result.complete).toBe(true);
+  });
+
+  it('is not complete for a booking with no declared weight', async () => {
+    const result = await remainingBulkTons(dataSourceReturning('0', '0'), 'b-1');
+
+    expect(result.complete).toBe(false);
+  });
+});
+
+describe('assertTruckCountWithinContainers', () => {
+  it('allows one truck per container', () => {
+    expect(() => assertTruckCountWithinContainers(3, 3)).not.toThrow();
+  });
+
+  it('rejects more trucks than containers', () => {
+    expect(() => assertTruckCountWithinContainers(4, 3)).toThrow(BadRequestException);
+  });
+
+  it('does not cap a bulk booking, which has no container count', () => {
+    expect(() => assertTruckCountWithinContainers(9, 0)).not.toThrow();
+  });
+});
diff --git a/apps/edr-freight-api/src/common/truck-load.util.ts b/apps/edr-freight-api/src/common/truck-load.util.ts
new file mode 100644
index 000000000..b65bc12fb
--- /dev/null
+++ b/apps/edr-freight-api/src/common/truck-load.util.ts
@@ -0,0 +1,148 @@
+import { BadRequestException, ConflictException } from '@nestjs/common';
+import type { DataSource } from 'typeorm';
+
+/** Two 20ft containers fit a truck bed; one 40ft fills it. */
+export const MAX_CONTAINERS_PER_TRUCK = 2;
+
+/**
+ * What one truck is being asked to carry, and the booking context to judge it
+ * against. `sizes` are the container_size labels of `containers`, in any order —
+ * only whether a 40ft is present matters.
+ */
+export interface TruckLoadCheck {
+  containers: string[];
+  /** Every container number on the booking. Empty means nothing to validate against. */
+  bookingContainers: string[];
+  sizes: string[];
+  /** Containers already riding another truck on this booking. */
+  assignedElsewhere?: string[];
+}
+
+/**
+ * The physical rule for loading one truck, shared by both haulage paths.
+ *
+ * A customer's own truck and an EDR last-mile truck obey the same physics, but
+ * the rule was implemented twice — once in CustomerTruckService, once in
+ * LastMileService — along with a byte-identical container-size query. Two copies
+ * of one rule drift, and that is exactly how the self-haul guard ended up
+ * enforced on one side only.
+ */
+export function assertTruckLoad({
+  containers,
+  bookingContainers,
+  sizes,
+  assignedElsewhere = [],
+}: TruckLoadCheck): void {
+  if (containers.length > MAX_CONTAINERS_PER_TRUCK) {
+    throw new BadRequestException(
+      `A truck carries at most ${MAX_CONTAINERS_PER_TRUCK} containers`,
+    );
+  }
+
+  // With no container list on the booking there is nothing to check membership
+  // against — bulk bookings take this path.
+  if (!bookingContainers.length) return;
+
+  for (const number of containers) {
+    if (!bookingContainers.includes(number)) {
+      throw new BadRequestException(
+        `Container ${number} is not one of this booking's containers`,
+      );
+    }
+    if (assignedElsewhere.includes(number)) {
+      throw new ConflictException(`Container ${number} is already loaded onto another truck`);
+    }
+  }
+
+  // A 40ft fills the bed, so it travels alone.
+  if (containers.length > 1 && sizes.some((size) => size.includes('40'))) {
+    throw new BadRequestException(
+      'A 40ft container fills the truck — assign only 1 container to this truck',
+    );
+  }
+}
+
+/** Never put more trucks on a booking than it has containers to fill them. */
+export function assertTruckCountWithinContainers(
+  truckCount: number,
+  bookingContainerCount: number,
+): void {
+  if (bookingContainerCount > 0 && truckCount > bookingContainerCount) {
+    throw new BadRequestException(
+      `Cannot assign more trucks than containers — this booking has ${bookingContainerCount} container(s) and ${truckCount} truck(s) requested.`,
+    );
+  }
+}
+
+/**
+ * How much of a bulk booking is still to be hauled. Counts trucks from BOTH
+ * haulage paths — a booking uses one or the other, and the rule ("trucks until
+ * no tonnage is left") is the same either way, so a single sum keeps them from
+ * disagreeing.
+ *
+ * Only departed trucks count: tonnage is known once the truck is weighed out.
+ */
+export async function remainingBulkTons(
+  dataSource: DataSource,
+  bookingId: string,
+): Promise<{ totalTons: number; hauledTons: number; remainingTons: number; complete: boolean }> {
+  const [row]: Array<{ totalTons: string | null; hauledTons: string | null }> =
+    await dataSource.query(
+      `SELECT COALESCE(b.cargo_total_weight_vgm, 0) AS "totalTons",
+              COALESCE((
+                SELECT SUM(va.net_weight_tons)
+                  FROM freight.last_mile_vehicle_assignments va
+                  JOIN freight.last_mile lm
+                    ON lm.id = va.last_mile_id AND lm.deleted_at IS NULL
+                 WHERE lm.booking_id = b.id
+                   AND va.deleted_at IS NULL
+                   AND va.departed_at IS NOT NULL
+              ), 0)
+            + COALESCE((
+                SELECT SUM(a.net_weight_tons)
+                  FROM freight.customer_truck_assignments a
+                 WHERE a.booking_id = b.id
+                   AND a.deleted_at IS NULL
+                   AND a.departed_at IS NOT NULL
+              ), 0) AS "hauledTons"
+         FROM freight.bookings b
+        WHERE b.id = $1 AND b.deleted_at IS NULL`,
+      [bookingId],
+    );
+  const totalTons = Number(row?.totalTons ?? 0);
+  const hauledTons = Number(row?.hauledTons ?? 0);
+  const remainingTons = Math.max(0, Math.round((totalTons - hauledTons) * 1000) / 1000);
+  return { totalTons, hauledTons, remainingTons, complete: totalTons > 0 && remainingTons <= 0 };
+}
+
+/** A fully-hauled bulk booking has nothing left for another truck to carry. */
+export function assertBulkTonnageRemains(totalTons: number, remainingTons: number): void {
+  if (totalTons > 0 && remainingTons <= 0) {
+    throw new BadRequestException(
+      'This bulk booking is fully hauled — no tonnage left to assign trucks for',
+    );
+  }
+}
+
+/**
+ * container_size labels for the given container numbers on a booking. Shared so
+ * the two haulage paths read sizes the same way.
+ */
+export async function bookingContainerSizes(
+  dataSource: DataSource,
+  bookingId: string,
+  numbers: string[],
+): Promise<string[]> {
+  if (!numbers.length) return [];
+  const rows: Array<{ size: string | null }> = await dataSource.query(
+    `SELECT bc.container_size AS "size"
+       FROM freight.booking_container_units bcu
+       JOIN freight.booking_container bc
+         ON bc.id = bcu.booking_container_id AND bc.deleted_at IS NULL
+      WHERE bc.booking_id = $1
+        AND UPPER(bcu.container_number) = ANY($2)
+        AND bcu.deleted_at IS NULL`,
+    [bookingId, numbers],
+  );
+  return rows.map((row) => (row.size ?? '').trim());
+}
diff --git a/apps/edr-freight-api/src/migrations/2400000000000-AddCustomerTruckExitWeights.ts b/apps/edr-freight-api/src/migrations/2400000000000-AddCustomerTruckExitWeights.ts
new file mode 100644
index 000000000..6cddae23d
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/2400000000000-AddCustomerTruckExitWeights.ts
@@ -0,0 +1,46 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Per-truck exit weights for customer self-haul, mirroring what
+ * `last_mile_vehicle_assignments` already carries for EDR trucks.
+ *
+ * A bulk booking is hauled away truck by truck until no tonnage is left, and the
+ * EDR side enforces that by summing `net_weight_tons` of departed trucks. The
+ * customer side had no net and no tare — only `gross_weight_kg`, which nothing
+ * in the live flow ever wrote (the release flow updated the EDR table only). So
+ * a self-haul bulk booking could take unlimited trucks: hauled tonnage always
+ * summed to zero.
+ *
+ * `gross_weight_kg` is left alone but note it holds TONNES despite its name —
+ * the weighing UI is in tonnes throughout. The new columns are named for the
+ * unit they actually hold.
+ */
+export class AddCustomerTruckExitWeights2400000000000 implements MigrationInterface {
+  name = 'AddCustomerTruckExitWeights2400000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.customer_truck_assignments
+        ADD COLUMN IF NOT EXISTS tare_weight_tons numeric(14,3) NULL,
+        ADD COLUMN IF NOT EXISTS net_weight_tons  numeric(14,3) NULL
+    `);
+
+    // Departed trucks are what the drawdown sums, so it reads this index.
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_customer_truck_departed"
+        ON freight.customer_truck_assignments (booking_id, departed_at)
+        WHERE deleted_at IS NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS freight."IDX_customer_truck_departed"`,
+    );
+    await queryRunner.query(`
+      ALTER TABLE freight.customer_truck_assignments
+        DROP COLUMN IF EXISTS tare_weight_tons,
+        DROP COLUMN IF EXISTS net_weight_tons
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/customer-truck.service.ts b/apps/edr-freight-api/src/modules/bookings/customer-truck.service.ts
index 7b0145db2..eb4699008 100644
--- a/apps/edr-freight-api/src/modules/bookings/customer-truck.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/customer-truck.service.ts
@@ -16,6 +16,13 @@ import {
   EDR_HAULAGE_CONFLICT_MESSAGE,
   usesEdrMileService,
 } from '../../common/mile-haulage.util';
+import {
+  assertBulkTonnageRemains,
+  assertTruckCountWithinContainers,
+  assertTruckLoad,
+  bookingContainerSizes,
+  remainingBulkTons,
+} from '../../common/truck-load.util';
 import { CustomerTruckAssignmentsRepository } from './customer-truck-assignments.repository';
 import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
 import { NotificationsService } from '../notifications/notifications.service';
@@ -71,39 +78,27 @@ export class CustomerTruckService {
     if (!isBulk && requested.length < 1) {
       throw new BadRequestException('Select at least one container for this truck');
     }
-    if (requested.length > 2) {
-      throw new BadRequestException('A truck carries at most 2 containers');
+
+    // Bulk is capped by tonnage, not container count: trucks may be added until
+    // the booking's declared weight has been hauled away. Container bookings are
+    // capped below by #trucks <= #containers.
+    if (isBulk) {
+      const { totalTons, remainingTons } = await remainingBulkTons(this.dataSource, bookingId);
+      assertBulkTonnageRemains(totalTons, remainingTons);
     }
 
     if (requested.length) {
       const bookingNumbers = await this.bookingContainerNumbers(bookingId);
-      // Never assign more trucks than the booking has containers.
       const existingTrucks = await this.dataSource
         .getRepository(CustomerTruckAssignment)
         .count({ where: { bookingId } });
-      if (existingTrucks + 1 > bookingNumbers.length) {
-        throw new BadRequestException(
-          `Cannot assign more trucks than containers — this booking has ${bookingNumbers.length} container(s) and ${existingTrucks} truck(s) already assigned.`,
-        );
-      }
-      for (const n of requested) {
-        if (!bookingNumbers.includes(n)) {
-          throw new BadRequestException(`Container ${n} is not one of this booking's containers`);
-        }
-      }
-      const alreadyAssigned = await this.assignedContainerNumbers(bookingId);
-      for (const n of requested) {
-        if (alreadyAssigned.includes(n)) {
-          throw new ConflictException(`Container ${n} is already loaded onto another truck`);
-        }
-      }
-      // Size cap: a 40ft container fills the truck.
-      const sizes = await this.containerSizes(bookingId, requested);
-      if (sizes.some((s) => s.includes('40')) && requested.length > 1) {
-        throw new BadRequestException(
-          'A 40ft container fills the truck — assign only 1 container to this truck',
-        );
-      }
+      assertTruckCountWithinContainers(existingTrucks + 1, bookingNumbers.length);
+      assertTruckLoad({
+        containers: requested,
+        bookingContainers: bookingNumbers,
+        sizes: await bookingContainerSizes(this.dataSource, bookingId, requested),
+        assignedElsewhere: await this.assignedContainerNumbers(bookingId),
+      });
     }
 
     await this.dataSource.transaction(async (manager) => {
@@ -195,28 +190,13 @@ export class CustomerTruckService {
     if (requested.length < 1) {
       throw new BadRequestException('Select at least one container for this truck');
     }
-    if (requested.length > 2) {
-      throw new BadRequestException('A truck carries at most 2 containers');
-    }
-    const bookingNumbers = await this.bookingContainerNumbers(bookingId);
-    for (const n of requested) {
-      if (!bookingNumbers.includes(n)) {
-        throw new BadRequestException(`Container ${n} is not one of this booking's containers`);
-      }
-    }
-    // Exclude THIS truck's own containers so re-saving the same set is allowed.
-    const assignedElsewhere = await this.assignedContainerNumbersExcept(bookingId, assignmentId);
-    for (const n of requested) {
-      if (assignedElsewhere.includes(n)) {
-        throw new ConflictException(`Container ${n} is already loaded onto another truck`);
-      }
-    }
-    const sizes = await this.containerSizes(bookingId, requested);
-    if (sizes.some((s) => s.includes('40')) && requested.length > 1) {
-      throw new BadRequestException(
-        'A 40ft container fills the truck — assign only 1 container to this truck',
-      );
-    }
+    assertTruckLoad({
+      containers: requested,
+      bookingContainers: await this.bookingContainerNumbers(bookingId),
+      sizes: await bookingContainerSizes(this.dataSource, bookingId, requested),
+      // Exclude THIS truck's own containers so re-saving the same set is allowed.
+      assignedElsewhere: await this.assignedContainerNumbersExcept(bookingId, assignmentId),
+    });
 
     await this.dataSource.transaction(async (manager) => {
       await manager.getRepository(CustomerTruckAssignment).update(assignmentId, {
@@ -344,27 +324,12 @@ export class CustomerTruckService {
     }
     // Capacity is size-based: a truck carries at most 2 containers, and a 40ft
     // container fills the truck (max 1) — mirror the addTruck/updateTruck rule.
-    if (requested.length > 2) {
-      throw new BadRequestException('A truck carries at most 2 containers');
-    }
-    const bookingNumbers = await this.bookingContainerNumbers(bookingId);
-    for (const n of requested) {
-      if (!bookingNumbers.includes(n)) {
-        throw new BadRequestException(`Container ${n} is not one of this booking's containers`);
-      }
-    }
-    const elsewhere = await this.assignedContainerNumbersExcept(bookingId, assignmentId);
-    for (const n of requested) {
-      if (elsewhere.includes(n)) {
-        throw new ConflictException(`Container ${n} is already loaded onto another truck`);
-      }
-    }
-    const sizes = await this.containerSizes(bookingId, requested);
-    if (sizes.some((s) => s.includes('40')) && requested.length > 1) {
-      throw new BadRequestException(
-        'A 40ft container fills the truck — load only 1 container onto this truck',
-      );
-    }
+    assertTruckLoad({
+      containers: requested,
+      bookingContainers: await this.bookingContainerNumbers(bookingId),
+      sizes: await bookingContainerSizes(this.dataSource, bookingId, requested),
+      assignedElsewhere: await this.assignedContainerNumbersExcept(bookingId, assignmentId),
+    });
 
     const grossTons = await this.vgmTonsForContainers(bookingId, requested);
     await this.dataSource.transaction(async (manager) => {
@@ -611,18 +576,4 @@ export class CustomerTruckService {
   }
 
   /** Contract container sizes (e.g. "20ft" / "40ft") for the given container numbers. */
-  private async containerSizes(bookingId: string, numbers: string[]): Promise<string[]> {
-    if (!numbers.length) return [];
-    const rows: Array<{ size: string | null }> = await this.dataSource.query(
-      `SELECT bc.container_size AS "size"
-         FROM freight.booking_container_units bcu
-         JOIN freight.booking_container bc
-           ON bc.id = bcu.booking_container_id AND bc.deleted_at IS NULL
-        WHERE bc.booking_id = $1
-          AND UPPER(bcu.container_number) = ANY($2)
-          AND bcu.deleted_at IS NULL`,
-      [bookingId, numbers],
-    );
-    return rows.map((r) => (r.size ?? '').trim());
-  }
 }
diff --git a/apps/edr-freight-api/src/modules/bookings/entities/customer-truck-assignment.entity.ts b/apps/edr-freight-api/src/modules/bookings/entities/customer-truck-assignment.entity.ts
index 6eeaba963..3892d2a97 100644
--- a/apps/edr-freight-api/src/modules/bookings/entities/customer-truck-assignment.entity.ts
+++ b/apps/edr-freight-api/src/modules/bookings/entities/customer-truck-assignment.entity.ts
@@ -39,6 +39,18 @@ export class CustomerTruckAssignment extends BaseEntity {
   @Column({ name: 'gross_weight_kg', type: 'numeric', precision: 14, scale: 2, nullable: true })
   grossWeightKg?: number | null;
 
+  /** Empty truck weight at the gate, in tonnes. Null until the truck departs. */
+  @Column({ name: 'tare_weight_tons', type: 'numeric', precision: 14, scale: 3, nullable: true })
+  tareWeightTons?: number | null;
+
+  /**
+   * Cargo actually taken (gross − tare), in tonnes. Drives the bulk drawdown:
+   * a bulk booking is hauled until the sum of this across departed trucks
+   * reaches its declared VGM. Mirrors last_mile_vehicle_assignments.
+   */
+  @Column({ name: 'net_weight_tons', type: 'numeric', precision: 14, scale: 3, nullable: true })
+  netWeightTons?: number | null;
+
   @Column({ name: 'departed_at', type: 'timestamptz', nullable: true })
   departedAt?: Date | null;
 
diff --git a/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts b/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
index aa293759c..b31a2ecbb 100644
--- a/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
+++ b/apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
@@ -12,6 +12,13 @@ import {
   SELF_HAUL_CONFLICT_MESSAGE,
   usesEdrMileService,
 } from '../../common/mile-haulage.util';
+import {
+  assertBulkTonnageRemains,
+  assertTruckCountWithinContainers,
+  assertTruckLoad,
+  bookingContainerSizes,
+  remainingBulkTons,
+} from '../../common/truck-load.util';
 import { BookingsRepository } from '../bookings/bookings.repository';
 import { DriversService } from '../drivers/drivers.service';
 import { SmsClientService } from '../notifications/sms-client.service';
@@ -621,20 +628,6 @@ export class LastMileService {
   }
 
   /** Contract container sizes (e.g. "20ft" / "40ft") for the given numbers. */
-  private async containerSizes(bookingId: string, numbers: string[]): Promise<string[]> {
-    if (!numbers.length) return [];
-    const rows: Array<{ size: string | null }> = await this.dataSource.query(
-      `SELECT bc.container_size AS "size"
-         FROM freight.booking_container_units bcu
-         JOIN freight.booking_container bc
-           ON bc.id = bcu.booking_container_id AND bc.deleted_at IS NULL
-        WHERE bc.booking_id = $1
-          AND UPPER(bcu.container_number) = ANY($2)
-          AND bcu.deleted_at IS NULL`,
-      [bookingId, numbers],
-    );
-    return rows.map((r) => (r.size ?? '').trim());
-  }
 
   /**
    * Bulk drawdown: how much of the booking's tonnage is still to be hauled —
@@ -647,26 +640,9 @@ export class LastMileService {
     remainingTons: number;
     complete: boolean;
   }> {
-    const [row]: Array<{ totalTons: string | null; hauledTons: string | null }> =
-      await this.dataSource.query(
-        `SELECT COALESCE(b.cargo_total_weight_vgm, 0) AS "totalTons",
-                COALESCE((
-                  SELECT SUM(va.net_weight_tons)
-                    FROM freight.last_mile_vehicle_assignments va
-                    JOIN freight.last_mile lm
-                      ON lm.id = va.last_mile_id AND lm.deleted_at IS NULL
-                   WHERE lm.booking_id = b.id
-                     AND va.deleted_at IS NULL
-                     AND va.departed_at IS NOT NULL
-                ), 0) AS "hauledTons"
-           FROM freight.bookings b
-          WHERE b.id = $1 AND b.deleted_at IS NULL`,
-        [bookingId],
-      );
-    const totalTons = Number(row?.totalTons ?? 0);
-    const hauledTons = Number(row?.hauledTons ?? 0);
-    const remainingTons = Math.max(0, Math.round((totalTons - hauledTons) * 1000) / 1000);
-    return { totalTons, hauledTons, remainingTons, complete: totalTons > 0 && remainingTons <= 0 };
+    // Counts customer trucks as well as EDR ones — a booking hauls by one path
+    // or the other, and "until no tonnage is left" means the same either way.
+    return remainingBulkTons(this.dataSource, bookingId);
   }
 
   /**
@@ -691,11 +667,7 @@ export class LastMileService {
     );
     if ((booking?.freightType ?? '').toUpperCase() === 'BULK') {
       const { remainingTons, totalTons } = await this.remainingTonsForBooking(bookingId);
-      if (totalTons > 0 && remainingTons <= 0) {
-        throw new BadRequestException(
-          'This bulk booking is fully hauled — no tonnage left to assign trucks for',
-        );
-      }
+      assertBulkTonnageRemains(totalTons, remainingTons);
       return;
     }
 
@@ -705,33 +677,41 @@ export class LastMileService {
     const seen = new Set<string>();
     for (const vehicleId of desired) {
       const load = loads.get(vehicleId) ?? [];
-      if (load.length > 2) {
-        throw new BadRequestException('A truck carries at most 2 containers');
-      }
-      for (const n of load) {
-        if (!bookingNumbers.includes(n)) {
-          throw new BadRequestException(`Container ${n} is not one of this booking's containers`);
-        }
-        if (seen.has(n)) {
-          throw new ConflictException(`Container ${n} is already assigned to another truck`);
-        }
-        seen.add(n);
-      }
-      // A 40ft container fills the truck; only two 20ft share one.
-      if (load.length > 1) {
-        const sizes = await this.containerSizes(bookingId, load);
-        if (sizes.some((s) => s.includes('40'))) {
-          throw new BadRequestException(
-            'A 40ft container fills the truck — assign only 1 container to this truck',
-          );
-        }
-      }
+      assertTruckLoad({
+        containers: load,
+        bookingContainers: bookingNumbers,
+        sizes: await bookingContainerSizes(this.dataSource, bookingId, load),
+        assignedElsewhere: [...seen],
+      });
+      load.forEach((n) => seen.add(n));
     }
 
-    if (desired.length > bookingNumbers.length) {
-      throw new BadRequestException(
-        `Cannot assign more trucks than containers — this booking has ${bookingNumbers.length} container(s) and ${desired.length} truck(s) requested.`,
+    assertTruckCountWithinContainers(desired.length, bookingNumbers.length);
+  }
+
+  /**
+   * A truck that has already reached the customer cannot have its load rewritten
+   * — the containers on it are a delivered fact, not a plan. The customer side
+   * has locked this since it was built (`Cannot edit a truck that has already
+   * arrived`); the EDR side let a reassignment silently rewrite history.
+   */
+  private async assertNoArrivedVehicleChanged(
+    current: LastMileVehicleAssignment[],
+    desiredMap: Map<string, string[]>,
+  ): Promise<void> {
+    const loadKey = (list: string[]) => [...list].sort().join('|');
+    for (const assignment of current) {
+      if (!assignment.arrivedAt) continue;
+      const stillPresent = desiredMap.has(assignment.vehicleId);
+      const load = desiredMap.get(assignment.vehicleId) ?? [];
+      const currentLoad = (assignment.containers ?? []).map((c) =>
+        c.containerNumber.trim().toUpperCase(),
       );
+      if (!stillPresent || loadKey(load) !== loadKey(currentLoad)) {
+        throw new ConflictException(
+          'This truck has already arrived — its load can no longer be changed or removed',
+        );
+      }
     }
   }
 
@@ -766,6 +746,8 @@ export class LastMileService {
       where: { lastMileId: id },
       relations: { containers: true },
     });
+    await this.assertNoArrivedVehicleChanged(current, desiredMap);
+
     const junctionSet = new Set(current.map((a) => a.vehicleId));
     // Fold the legacy vehicleId into the release set — a vehicle assigned via the
     // old single-vehicle path has no junction row but must still be freed.
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
index 1deedd14d..ee1438fcf 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
@@ -2978,6 +2978,31 @@ export class WarehouseInventoryService {
             netTons,
           ],
         );
+        // Customer self-haul: the same exit record on the customer's own truck.
+        // Without it a self-haul bulk booking never draws down — hauled tonnage
+        // summed to zero and the booking could take unlimited trucks. Matched by
+        // plate rather than container so bulk trucks (which carry none) count.
+        await manager.query(
+          `UPDATE freight.customer_truck_assignments a
+              SET departed_at = COALESCE($3::timestamptz, NOW()),
+                  arrived_at = COALESCE(a.arrived_at, NOW()),
+                  gross_weight_kg = $4,
+                  tare_weight_tons = $5,
+                  net_weight_tons = $6,
+                  updated_at = NOW()
+            WHERE a.booking_id = $1
+              AND UPPER(a.plate_number) = UPPER($2)
+              AND a.departed_at IS NULL
+              AND a.deleted_at IS NULL`,
+          [
+            item.bookingId,
+            dto.truckPlateNumber.trim(),
+            dto.gateOutTime ?? null,
+            grossTons,
+            tareTons,
+            netTons,
+          ],
+        );
       }
       await this.activityLog.record(
         {
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/ReleaseOrderModal.tsx b/apps/edr-freight-web/backoffice/src/components/warehouses/ReleaseOrderModal.tsx
index 26f2334b9..5f0a8a092 100644
--- a/apps/edr-freight-web/backoffice/src/components/warehouses/ReleaseOrderModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/ReleaseOrderModal.tsx
@@ -202,6 +202,24 @@ export function ReleaseOrderModal({ opened, onClose, item, truckPrefill }: Relea
     );
   }, [opened, truckPrefill, isExitStep, lastMileTrucks]);
 
+  // The same for a customer self-haul truck. The prefill above reads the
+  // booking.customer_truck_* columns, but multi-truck self-haul writes the plate
+  // and driver to customer_truck_assignments and leaves those columns null — so
+  // a booking with a truck on file still opened this form blank. Only auto-fills
+  // a single truck: with several, the operator picks which one is at the gate.
+  useEffect(() => {
+    if (!opened || truckPrefill || isExitStep) return;
+    if (customerTrucks.length !== 1) return;
+    const [truck] = customerTrucks;
+    setTruckPlateNumber((p) => p || truck.plateNumber || '');
+    setDriverName((p) => p || truck.driverName || '');
+    setTruckType((p) => p || truck.truckType || '');
+    setContainerNumbers((prev) => {
+      const loaded = (truck.containers ?? []).map((c) => c.containerNumber).filter(Boolean);
+      return prev.every((n) => !n) && loaded.length ? loaded : prev;
+    });
+  }, [opened, truckPrefill, isExitStep, customerTrucks]);
+
   // Registered trucks for THIS booking, from both sources: EDR last-mile
   // (truckPrefill) and the customer portal (customer_truck_assignments).
   const assignedTruckOptions = [